@athenaintel/react 0.43.0 → 0.48.0

package/dist/agent-runtime/src/thread-handoff-protocol.d.ts

@@ -0,0 +1,756 @@
+/**
+ * Cross-surface "Continue on…" thread handoff — the client half of agora's
+ * `/api/handoffs` protocol shared by Spaces, the mobile app, Athena in Chrome,
+ * the desktop app and the Office add-ins.
+ *
+ * A handoff carries no conversation content beyond the source composer's
+ * unsent draft. The server binds an opaque `handoff_id` to the durable thread,
+ * and the destination surface claims that id and acknowledges once it owns the
+ * thread. The source surface closes its own copilot only after that
+ * acknowledgement; nothing switches surfaces on its own.
+ */
+import { z } from 'zod';
+/** Destinations a readiness response reports a row for (a closed set older readers validate). */
+export declare const HANDOFF_DESTINATIONS: readonly ['chrome', 'mobile', 'word', 'powerpoint', 'excel'];
+export type HandoffDestination = (typeof HANDOFF_DESTINATIONS)[number];
+/**
+ * Every destination a handoff record can name. `spaces` lands on a Spaces link
+ * or an open Spaces tab; `next` is "wherever I pick up next" (the first of the
+ * four surfaces to come to the front and accept it); `desktop` is the desktop
+ * app, created through `/api/handoffs/desktop` but polled like the rest.
+ */
+export declare const THREAD_HANDOFF_DESTINATIONS: readonly ["chrome", "mobile", "word", "powerpoint", "excel", "spaces", "next", "desktop"];
+export type ThreadHandoffDestination = (typeof THREAD_HANDOFF_DESTINATIONS)[number];
+/** The four surfaces of a phase-one handover; each can claim a `next` handoff. */
+export declare const PICKUP_SURFACES: readonly ['spaces', 'mobile', 'chrome', 'desktop'];
+export type PickupSurface = (typeof PICKUP_SURFACES)[number];
+/** What "Continue on…" offers among the four surfaces, in picker order. */
+export declare const SURFACE_HANDOFF_DESTINATIONS: readonly ['spaces', 'mobile', 'chrome', 'desktop', 'next'];
+export type SurfaceHandoffDestination = (typeof SURFACE_HANDOFF_DESTINATIONS)[number];
+/** The source composer's unsent text that travels prefilled, never sent. */
+export declare const MAX_HANDOFF_DRAFT_LENGTH = 4000;
+/**
+ * How the person chose to continue. `voice` is an offer the destination shows
+ * ("Continue by voice"); it never starts a microphone by itself. Older servers
+ * omit it, which reads as `text`.
+ */
+export declare const handoffModeSchema: z.ZodEnum<{
+    text: "text";
+    voice: "voice";
+}>;
+export type HandoffMode = z.infer<typeof handoffModeSchema>;
+/** Destinations that can continue by voice: the four surfaces and "next". */
+export declare const isVoiceHandoffDestination: (destination: ThreadHandoffDestination) => boolean;
+export declare const OFFICE_HANDOFF_DESTINATIONS: readonly ['word', 'powerpoint', 'excel'];
+export type OfficeHandoffDestination = (typeof OFFICE_HANDOFF_DESTINATIONS)[number];
+export declare const officeLaunchModeSchema: z.ZodEnum<{
+    invitation: "invitation";
+    new_document: "new_document";
+}>;
+export type OfficeLaunchMode = z.infer<typeof officeLaunchModeSchema>;
+/** Destinations agora brokers; Chrome is launched page-side by the extension. */
+export declare const SERVER_HANDOFF_DESTINATIONS: readonly ["mobile", "word", "powerpoint", "excel"];
+export type ServerHandoffDestination = (typeof SERVER_HANDOFF_DESTINATIONS)[number];
+export type HandoffSource = 'spaces' | 'chrome' | 'mobile' | 'word' | 'powerpoint' | 'excel' | 'desktop';
+export declare const handoffEnvironmentSchema: z.ZodEnum<{
+    localhost: "localhost";
+    production: "production";
+    staging: "staging";
+}>;
+export type HandoffEnvironment = z.infer<typeof handoffEnvironmentSchema>;
+export declare const handoffStateSchema: z.ZodEnum<{
+    acknowledged: "acknowledged";
+    claimed: "claimed";
+    failed: "failed";
+    issued: "issued";
+    launched: "launched";
+}>;
+export type HandoffState = z.infer<typeof handoffStateSchema>;
+export declare const handoffReadinessStateSchema: z.ZodEnum<{
+    not_registered: "not_registered";
+    registered: "registered";
+    stale: "stale";
+    unknown: "unknown";
+    unsupported: "unsupported";
+}>;
+export type HandoffReadinessState = z.infer<typeof handoffReadinessStateSchema>;
+export declare const destinationReadinessSchema: z.ZodObject<{
+    destination: z.ZodEnum<{
+        chrome: "chrome";
+        excel: "excel";
+        mobile: "mobile";
+        powerpoint: "powerpoint";
+        word: "word";
+    }>;
+    state: z.ZodEnum<{
+        not_registered: "not_registered";
+        registered: "registered";
+        stale: "stale";
+        unknown: "unknown";
+        unsupported: "unsupported";
+    }>;
+    last_seen_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    marketplace_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DestinationReadiness = z.infer<typeof destinationReadinessSchema>;
+export declare const handoffReadinessResponseSchema: z.ZodObject<{
+    environment: z.ZodEnum<{
+        localhost: "localhost";
+        production: "production";
+        staging: "staging";
+    }>;
+    destinations: z.ZodArray<z.ZodObject<{
+        destination: z.ZodEnum<{
+            chrome: "chrome";
+            excel: "excel";
+            mobile: "mobile";
+            powerpoint: "powerpoint";
+            word: "word";
+        }>;
+        state: z.ZodEnum<{
+            not_registered: "not_registered";
+            registered: "registered";
+            stale: "stale";
+            unknown: "unknown";
+            unsupported: "unsupported";
+        }>;
+        last_seen_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        marketplace_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    supports_office_invitations: z.ZodOptional<z.ZodBoolean>;
+    supports_desktop_source: z.ZodOptional<z.ZodBoolean>;
+    supports_surface_destinations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type HandoffReadinessResponse = z.infer<typeof handoffReadinessResponseSchema>;
+export declare const supportsDesktopHandoffSource: (readiness: HandoffReadinessResponse | null | undefined) => boolean;
+/** Whether the server can broker the four-surface destinations; absent means an older agora. */
+export declare const supportsSurfaceHandoffDestinations: (readiness: HandoffReadinessResponse | null | undefined) => boolean;
+export declare const threadHandoffViewSchema: z.ZodObject<{
+    handoff_id: z.ZodString;
+    thread_id: z.ZodString;
+    session_asset_id: z.ZodNullable<z.ZodString>;
+    source: z.ZodString;
+    destination: z.ZodEnum<{
+        chrome: "chrome";
+        desktop: "desktop";
+        excel: "excel";
+        mobile: "mobile";
+        next: "next";
+        powerpoint: "powerpoint";
+        spaces: "spaces";
+        word: "word";
+    }>;
+    office_launch_mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        invitation: "invitation";
+        new_document: "new_document";
+    }>>>;
+    environment: z.ZodEnum<{
+        localhost: "localhost";
+        production: "production";
+        staging: "staging";
+    }>;
+    state: z.ZodEnum<{
+        acknowledged: "acknowledged";
+        claimed: "claimed";
+        failed: "failed";
+        issued: "issued";
+        launched: "launched";
+    }>;
+    issued_at: z.ZodString;
+    expires_at: z.ZodString;
+    claimed_at: z.ZodNullable<z.ZodString>;
+    acknowledged_at: z.ZodNullable<z.ZodString>;
+    failure_reason: z.ZodNullable<z.ZodString>;
+    push_delivered: z.ZodNullable<z.ZodBoolean>;
+    claimed_surface: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        chrome: "chrome";
+        desktop: "desktop";
+        mobile: "mobile";
+        spaces: "spaces";
+    }>>>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        text: "text";
+        voice: "voice";
+    }>>;
+    draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type ThreadHandoffView = z.infer<typeof threadHandoffViewSchema>;
+export declare const mobileHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"mobile">;
+    push_attempted: z.ZodBoolean;
+    push_delivered: z.ZodBoolean;
+    device_count: z.ZodNumber;
+    link_url: z.ZodString;
+    scheme_url: z.ZodString;
+}, z.core.$strip>;
+export type MobileHandoffLaunch = z.infer<typeof mobileHandoffLaunchSchema>;
+export declare const officeHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"office">;
+    host: z.ZodEnum<{
+        excel: "excel";
+        powerpoint: "powerpoint";
+        word: "word";
+    }>;
+    desktop_url: z.ZodString;
+    template_url: z.ZodString;
+    web_url: z.ZodString;
+    marketplace_url: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type OfficeHandoffLaunch = z.infer<typeof officeHandoffLaunchSchema>;
+export declare const officeInvitationLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"office_invitation">;
+    host: z.ZodEnum<{
+        excel: "excel";
+        powerpoint: "powerpoint";
+        word: "word";
+    }>;
+}, z.core.$strip>;
+export type OfficeInvitationLaunch = z.infer<typeof officeInvitationLaunchSchema>;
+export declare const chromeHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"chrome">;
+}, z.core.$strip>;
+/** Spaces lands on `url`; an open Spaces tab also finds the record on its own. */
+export declare const spacesHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"spaces">;
+    url: z.ZodString;
+}, z.core.$strip>;
+export type SpacesHandoffLaunch = z.infer<typeof spacesHandoffLaunchSchema>;
+/** Nothing to open: the next surface to come to the front offers it. */
+export declare const nextHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"next">;
+}, z.core.$strip>;
+/** The desktop app: `scheme_url` on the same computer; from a phone, it finds the record itself. */
+export declare const desktopThreadHandoffLaunchSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"desktop">;
+    scheme_url: z.ZodString;
+    download_url: z.ZodString;
+    deployment_url: z.ZodString;
+    protocol_version: z.ZodLiteral<1>;
+}, z.core.$strip>;
+export type DesktopThreadHandoffLaunch = z.infer<typeof desktopThreadHandoffLaunchSchema>;
+export declare const handoffLaunchSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"mobile">;
+    push_attempted: z.ZodBoolean;
+    push_delivered: z.ZodBoolean;
+    device_count: z.ZodNumber;
+    link_url: z.ZodString;
+    scheme_url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"office">;
+    host: z.ZodEnum<{
+        excel: "excel";
+        powerpoint: "powerpoint";
+        word: "word";
+    }>;
+    desktop_url: z.ZodString;
+    template_url: z.ZodString;
+    web_url: z.ZodString;
+    marketplace_url: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"office_invitation">;
+    host: z.ZodEnum<{
+        excel: "excel";
+        powerpoint: "powerpoint";
+        word: "word";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"chrome">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"spaces">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"next">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"desktop">;
+    scheme_url: z.ZodString;
+    download_url: z.ZodString;
+    deployment_url: z.ZodString;
+    protocol_version: z.ZodLiteral<1>;
+}, z.core.$strip>], "kind">;
+export type HandoffLaunch = z.infer<typeof handoffLaunchSchema>;
+export declare const createThreadHandoffResponseSchema: z.ZodObject<{
+    handoff: z.ZodObject<{
+        handoff_id: z.ZodString;
+        thread_id: z.ZodString;
+        session_asset_id: z.ZodNullable<z.ZodString>;
+        source: z.ZodString;
+        destination: z.ZodEnum<{
+            chrome: "chrome";
+            desktop: "desktop";
+            excel: "excel";
+            mobile: "mobile";
+            next: "next";
+            powerpoint: "powerpoint";
+            spaces: "spaces";
+            word: "word";
+        }>;
+        office_launch_mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            invitation: "invitation";
+            new_document: "new_document";
+        }>>>;
+        environment: z.ZodEnum<{
+            localhost: "localhost";
+            production: "production";
+            staging: "staging";
+        }>;
+        state: z.ZodEnum<{
+            acknowledged: "acknowledged";
+            claimed: "claimed";
+            failed: "failed";
+            issued: "issued";
+            launched: "launched";
+        }>;
+        issued_at: z.ZodString;
+        expires_at: z.ZodString;
+        claimed_at: z.ZodNullable<z.ZodString>;
+        acknowledged_at: z.ZodNullable<z.ZodString>;
+        failure_reason: z.ZodNullable<z.ZodString>;
+        push_delivered: z.ZodNullable<z.ZodBoolean>;
+        claimed_surface: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            chrome: "chrome";
+            desktop: "desktop";
+            mobile: "mobile";
+            spaces: "spaces";
+        }>>>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            voice: "voice";
+        }>>;
+        draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    launch: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"mobile">;
+        push_attempted: z.ZodBoolean;
+        push_delivered: z.ZodBoolean;
+        device_count: z.ZodNumber;
+        link_url: z.ZodString;
+        scheme_url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"office">;
+        host: z.ZodEnum<{
+            excel: "excel";
+            powerpoint: "powerpoint";
+            word: "word";
+        }>;
+        desktop_url: z.ZodString;
+        template_url: z.ZodString;
+        web_url: z.ZodString;
+        marketplace_url: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"office_invitation">;
+        host: z.ZodEnum<{
+            excel: "excel";
+            powerpoint: "powerpoint";
+            word: "word";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"chrome">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"spaces">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"next">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"desktop">;
+        scheme_url: z.ZodString;
+        download_url: z.ZodString;
+        deployment_url: z.ZodString;
+        protocol_version: z.ZodLiteral<1>;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type CreateThreadHandoffResponse = z.infer<typeof createThreadHandoffResponseSchema>;
+export interface CreateThreadHandoffInput {
+    threadId: string;
+    destination: ThreadHandoffDestination;
+    source: HandoffSource;
+    officeLaunchMode?: OfficeLaunchMode;
+    /** An observed workspace precondition, never an authorization grant. */
+    expectedWorkspaceId?: string;
+    /** The composer's unsent text; the destination prefills it and never sends it. */
+    draft?: string;
+    /** `voice` offers "Continue by voice" on the destination. Omitted means text. */
+    mode?: HandoffMode;
+}
+/** A phone invites the computer's pane; other sources keep their existing launch. */
+export declare function resolveOfficeHandoffLaunchMode({ source, destination, officeLaunchMode, }: CreateThreadHandoffInput): OfficeLaunchMode | undefined;
+/** The same request body for every host's authenticated HTTP adapter. */
+export declare function threadHandoffCreateBody({ threadId, destination, source, officeLaunchMode, expectedWorkspaceId, draft, mode: handoffMode, }: CreateThreadHandoffInput): {
+    thread_id: string;
+    destination: "chrome" | "desktop" | "excel" | "mobile" | "next" | "powerpoint" | "spaces" | "word";
+    source: HandoffSource;
+    expected_workspace_id?: string | undefined;
+    office_launch_mode?: "invitation" | "new_document" | undefined;
+    draft?: string | undefined;
+    mode?: "voice" | undefined;
+};
+/** Keep a draft within the server's limit at a character boundary; never send more. */
+export declare const clampHandoffDraft: (draft: string) => string;
+/**
+ * Where an HTTP adapter sends a create. The desktop app has its own protocol
+ * (its record also carries asset tabs), so `desktop` posts a conversation-only
+ * desktop handoff to `/desktop`; everything else posts to `/api/handoffs`.
+ * Pair with {@link parseThreadHandoffCreateResponse}.
+ */
+export declare function threadHandoffCreateRequest(input: CreateThreadHandoffInput): {
+    path: '' | '/desktop';
+    body: Record<string, unknown>;
+};
+/** Parse either create reply into the one shape the shared flow waits on. */
+export declare function parseThreadHandoffCreateResponse(input: Pick<CreateThreadHandoffInput, 'destination'>, payload: unknown): CreateThreadHandoffResponse;
+/** Body of `POST /api/handoffs/claim`. `surface` is required for a `next` pickup. */
+export declare function threadHandoffClaimBody({ handoffId, destination, surfaceInstance, surface, }: {
+    handoffId?: string;
+    destination: Exclude<ThreadHandoffDestination, 'desktop'>;
+    surfaceInstance: string;
+    surface?: PickupSurface;
+}): {
+    handoff_id?: string | undefined;
+    destination: "chrome" | "excel" | "mobile" | "next" | "powerpoint" | "spaces" | "word";
+    surface_instance: string;
+    surface?: "chrome" | "desktop" | "mobile" | "spaces" | undefined;
+};
+/** The most ticket ids a receiver may ask `/pending` to skip. */
+export declare const MAX_PENDING_EXCLUDE = 20;
+/**
+ * The ids a receiver asks `/pending` to skip (declined here, or issued here),
+ * newest last in, bounded to the server's limit and to the id shape it issues.
+ * A filter only: the server still binds every candidate to the caller.
+ */
+export declare function pendingExcludeIds(ids: Iterable<string>): string[];
+/**
+ * A receiver's `exclude`: the newest half of what it issued and the newest half of what it
+ * declined (each oldest first, as a Set keeps them). Neither kind can crowd the other out of
+ * the server's bound, so a long-lived tab's old declines never hide its newest own ticket and
+ * many sends never drop its latest "Not now".
+ */
+export declare function pickupExcludeIds({ issuedHere, declined, }: {
+    issuedHere: Iterable<string>;
+    declined: Iterable<string>;
+}): string[];
+/** `/pending?destination=…&exclude=…` relative to `/api/handoffs`. */
+export declare function pendingHandoffPath({ destination, exclude, }: {
+    destination: Exclude<ThreadHandoffDestination, 'desktop'> | 'desktop';
+    exclude?: Iterable<string>;
+}): string;
+export declare const claimThreadHandoffResponseSchema: z.ZodObject<{
+    handoff: z.ZodObject<{
+        handoff_id: z.ZodString;
+        thread_id: z.ZodString;
+        session_asset_id: z.ZodNullable<z.ZodString>;
+        source: z.ZodString;
+        destination: z.ZodEnum<{
+            chrome: "chrome";
+            desktop: "desktop";
+            excel: "excel";
+            mobile: "mobile";
+            next: "next";
+            powerpoint: "powerpoint";
+            spaces: "spaces";
+            word: "word";
+        }>;
+        office_launch_mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            invitation: "invitation";
+            new_document: "new_document";
+        }>>>;
+        environment: z.ZodEnum<{
+            localhost: "localhost";
+            production: "production";
+            staging: "staging";
+        }>;
+        state: z.ZodEnum<{
+            acknowledged: "acknowledged";
+            claimed: "claimed";
+            failed: "failed";
+            issued: "issued";
+            launched: "launched";
+        }>;
+        issued_at: z.ZodString;
+        expires_at: z.ZodString;
+        claimed_at: z.ZodNullable<z.ZodString>;
+        acknowledged_at: z.ZodNullable<z.ZodString>;
+        failure_reason: z.ZodNullable<z.ZodString>;
+        push_delivered: z.ZodNullable<z.ZodBoolean>;
+        claimed_surface: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            chrome: "chrome";
+            desktop: "desktop";
+            mobile: "mobile";
+            spaces: "spaces";
+        }>>>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            voice: "voice";
+        }>>;
+        draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ClaimThreadHandoffResponse = z.infer<typeof claimThreadHandoffResponseSchema>;
+/** `GET /api/handoffs/pending` answers `null` (not 404) when nothing waits. */
+export declare const pendingThreadHandoffResponseSchema: z.ZodNullable<z.ZodObject<{
+    handoff: z.ZodObject<{
+        handoff_id: z.ZodString;
+        thread_id: z.ZodString;
+        session_asset_id: z.ZodNullable<z.ZodString>;
+        source: z.ZodString;
+        destination: z.ZodEnum<{
+            chrome: "chrome";
+            desktop: "desktop";
+            excel: "excel";
+            mobile: "mobile";
+            next: "next";
+            powerpoint: "powerpoint";
+            spaces: "spaces";
+            word: "word";
+        }>;
+        office_launch_mode: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            invitation: "invitation";
+            new_document: "new_document";
+        }>>>;
+        environment: z.ZodEnum<{
+            localhost: "localhost";
+            production: "production";
+            staging: "staging";
+        }>;
+        state: z.ZodEnum<{
+            acknowledged: "acknowledged";
+            claimed: "claimed";
+            failed: "failed";
+            issued: "issued";
+            launched: "launched";
+        }>;
+        issued_at: z.ZodString;
+        expires_at: z.ZodString;
+        claimed_at: z.ZodNullable<z.ZodString>;
+        acknowledged_at: z.ZodNullable<z.ZodString>;
+        failure_reason: z.ZodNullable<z.ZodString>;
+        push_delivered: z.ZodNullable<z.ZodBoolean>;
+        claimed_surface: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            chrome: "chrome";
+            desktop: "desktop";
+            mobile: "mobile";
+            spaces: "spaces";
+        }>>>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            voice: "voice";
+        }>>;
+        draft: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+/**
+ * Receiving half of the protocol: an open Spaces tab, the extension or the
+ * phone finds a handoff sent to it (or to `next`), claims it exactly once and
+ * reports the outcome. Every call is bound server-side to the signed-in
+ * person, workspace and environment. The desktop app is not a destination
+ * here: its own receiver claims `/api/handoffs/desktop` and acknowledges with
+ * per-asset results, which is why `desktop` is excluded from these calls.
+ */
+export interface ThreadHandoffReceiverTransport {
+    getPending: (options: {
+        destination: Exclude<ThreadHandoffDestination, 'desktop'>;
+        /** Tickets this receiver declined or issued itself; the newest other one is returned. */
+        exclude?: readonly string[];
+        signal?: AbortSignal;
+    }) => Promise<ClaimThreadHandoffResponse | null>;
+    claim: (options: {
+        handoffId?: string;
+        destination: Exclude<ThreadHandoffDestination, 'desktop'>;
+        surfaceInstance: string;
+        surface?: PickupSurface;
+        signal?: AbortSignal;
+    }) => Promise<ClaimThreadHandoffResponse>;
+    acknowledge: (options: {
+        handoffId: string;
+        outcome: 'acknowledged' | 'failed';
+        reason?: string;
+        surfaceInstance: string;
+        signal?: AbortSignal;
+    }) => Promise<ThreadHandoffView>;
+}
+/**
+ * Whether a pending handoff should be offered on this surface: still open,
+ * not one this device issued itself, and not one it already declined.
+ * Offering never claims; the person's tap does.
+ */
+export declare function shouldOfferPendingHandoff({ pending, issuedHere, declined, now, }: {
+    pending: ThreadHandoffView | null | undefined;
+    issuedHere: ReadonlySet<string>;
+    declined: ReadonlySet<string>;
+    now?: number;
+}): boolean;
+/**
+ * Surface-specific HTTP adapter. Olympus binds it to `apiClient`; the
+ * extension binds it to its authenticated fetch. Both must resolve (not
+ * reject) with parsed responses so the flow can attribute failures.
+ */
+export interface ThreadHandoffTransport {
+    getReadiness: (options: {
+        signal?: AbortSignal;
+    }) => Promise<HandoffReadinessResponse>;
+    createHandoff: (input: CreateThreadHandoffInput & {
+        signal?: AbortSignal;
+    }) => Promise<CreateThreadHandoffResponse>;
+    getHandoff: (options: {
+        handoffId: string;
+        signal?: AbortSignal;
+    }) => Promise<ThreadHandoffView>;
+}
+export declare const HANDOFF_DESTINATION_LABELS: Record<HandoffDestination, string>;
+/** Picker labels for every destination a "Continue on…" row can name. */
+export declare const THREAD_HANDOFF_DESTINATION_LABELS: Record<ThreadHandoffDestination, string>;
+/** "Pick up your conversation from your phone?" — a destination's offer, before any claim. */
+export declare const pickUpOfferLabel: (source: string) => string;
+/** "Continued from your phone" — the divider a destination shows where it picked up. */
+export declare const continuedFromLabel: (source: string) => string;
+/** "Pick up your conversation from your phone?" — a destination's offer outside its own window. */
+export declare const pickUpFromLabel: (source: string) => string;
+/** What a source says once a `next` handoff was picked up somewhere. */
+export declare const pickedUpOnLabel: (surface: PickupSurface | null | undefined) => string;
+export declare const driverSurfaceForChannel: (channel: string | null | undefined) => PickupSurface | null;
+/**
+ * "Driving on your phone" when another of the four surfaces sent last;
+ * `null` when this surface is the driver or the driver is unknown.
+ */
+export declare const drivingOnLabel: ({ lastChannel, here, }: {
+    lastChannel: string | null | undefined;
+    here: PickupSurface;
+}) => string | null;
+/** A landing the destination shows once it owns the thread. */
+export interface HandoffLanding {
+    handoffId: string;
+    threadId: string;
+    /** The raw `source` of the record (`spaces`, `mobile`, …). */
+    source: string;
+    /** Prefill it; never send it. `null` when the source had nothing typed. */
+    draft: string | null;
+    /**
+     * The person chose to continue by voice. The host offers a one-tap
+     * "Continue by voice"; nothing starts the microphone on its own.
+     */
+    continueByVoice: boolean;
+}
+export declare const handoffLandingFromView: (view: ThreadHandoffView) => HandoffLanding;
+export declare const isOfficeHandoffDestination: (destination: ThreadHandoffDestination) => destination is OfficeHandoffDestination;
+export declare const isServerHandoffDestination: (destination: HandoffDestination) => destination is ServerHandoffDestination;
+export declare const isPickupSurface: (value: unknown) => value is PickupSurface;
+/** Index a readiness response by destination; missing rows read as `unknown`. */
+export declare const readinessByDestination: (response: HandoffReadinessResponse | null | undefined) => Record<HandoffDestination, DestinationReadiness>;
+/**
+ * How a mobile handoff should be presented before the phone answers.
+ *
+ * - `app`: a fresh push token exists — the phone gets a notification and the
+ *   QR is only offered as a secondary path.
+ * - `qr`: no usable device is known — lead with the QR / link.
+ */
+export type MobileLaunchMode = 'app' | 'qr';
+export declare const selectMobileLaunchMode: (readiness: DestinationReadiness | null | undefined) => MobileLaunchMode;
+/**
+ * What a "Continue in…" row should say for a destination given its readiness.
+ * Shared so Spaces and the extension render identical copy.
+ */
+export interface HandoffDestinationPresentation {
+    destination: HandoffDestination;
+    label: string;
+    /** Secondary line under the label; `null` when the row needs no caveat. */
+    detail: string | null;
+    /**
+     * `install` rows do not create a handoff — they point at install help;
+     * `unavailable` rows are disabled.
+     */
+    action: 'handoff' | 'install' | 'unavailable';
+}
+export declare const presentHandoffDestination: ({ destination, readiness, }: {
+    destination: HandoffDestination;
+    readiness: DestinationReadiness | null | undefined;
+}) => HandoffDestinationPresentation;
+export type HandoffOutcome = {
+    status: 'acknowledged';
+    handoff: ThreadHandoffView;
+} | {
+    status: 'failed';
+    handoff: ThreadHandoffView | null;
+    reason: string;
+} | {
+    status: 'timeout';
+    handoff: ThreadHandoffView | null;
+} | {
+    status: 'cancelled';
+    handoff: ThreadHandoffView | null;
+};
+export declare const isTerminalHandoffState: (state: HandoffState) => boolean;
+export interface WaitForHandoffOutcomeOptions {
+    transport: Pick<ThreadHandoffTransport, 'getHandoff'>;
+    handoffId: string;
+    /** Wall-clock budget; mobile pushes typically land in seconds, Office launches in tens of seconds. */
+    timeoutMs: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onUpdate?: (handoff: ThreadHandoffView) => void;
+    /** Injected for tests. */
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Poll one handoff until the destination acknowledges, the server marks it
+ * failed, the budget elapses, or the caller aborts. Each request is bound to
+ * the remaining budget so a stalled response cannot outlive the deadline.
+ * Retryable transport errors are retried within the budget; permanent ones
+ * (auth, wrong deployment, malformed payload) fail immediately with their
+ * actionable message. The last known view is reported.
+ */
+export declare function waitForHandoffOutcome({ transport, handoffId, timeoutMs, pollIntervalMs, signal, onUpdate, now, sleep, }: WaitForHandoffOutcomeOptions): Promise<HandoffOutcome>;
+/** Error raised by a transport when the server no longer knows the handoff (404). */
+export declare class HandoffGoneError extends Error {
+    constructor(handoffId: string);
+}
+export declare const isHandoffGoneError: (error: unknown) => error is HandoffGoneError;
+/**
+ * Transport failure that polling the same handoff can never recover from:
+ * the session is signed out, the token belongs to another deployment, the
+ * server rejected the request, or the payload did not match the schema.
+ */
+export declare class HandoffPermanentError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare const isHandoffPermanentError: (error: unknown) => error is HandoffPermanentError;
+export type HandoffTransportErrorKind = 'gone' | 'permanent' | 'retryable';
+/**
+ * Shared classification for both transports: only network failures and
+ * retryable server statuses keep the poll alive. Schema mismatches surface as
+ * `ZodError` from either adapter and are permanent.
+ */
+export declare const classifyHandoffTransportError: (error: unknown) => HandoffTransportErrorKind;
+/** 5xx, timeouts and rate limits may clear on the next poll; any other 4xx will not. */
+export declare const isRetryableHandoffHttpStatus: (status: number) => boolean;
+/**
+ * Map a non-2xx status to the transport error the poll loop understands.
+ * `detail` is the server's actionable message when it sent one.
+ */
+export declare const handoffHttpError: ({ handoffId, status, detail, }: {
+    handoffId: string;
+    status: number;
+    detail: string | null;
+}) => Error;
+export declare const describeHandoffTransportError: (error: unknown) => string;
+/** `?handoff=<id>` — the query parameter mobile-web and QR links carry. */
+export declare const HANDOFF_URL_PARAM = "handoff";
+/** `?continue_handoff=<id>` — where a continuation lands in Spaces (never a phone's ticket). */
+export declare const SPACES_HANDOFF_URL_PARAM = "continue_handoff";
+/**
+ * Read a handoff id from a URL. Ids are server-issued, URL-safe tokens; anything
+ * else is rejected so a tampered link never reaches the claim path.
+ */
+export declare const parseHandoffIdParam: (value: string | null | undefined) => string | null;
+/** Athena Mobile's custom URL scheme (`mobile-app-react-native/app.json` → `scheme`). */
+export declare const MOBILE_APP_SCHEME = "athenavisionapplication";
+/**
+ * Custom-scheme launch for a handoff — what a phone's browser opens when the
+ * Universal/App Link landed on mobile web instead of in the app. Mirrors
+ * agora's `_mobile_scheme_url`; carries only the opaque handoff id.
+ */
+export declare const buildMobileHandoffSchemeUrl: ({ handoffId }: {
+    handoffId: string;
+}) => string;