/**
 * App-channel transport contract.
 *
 * An embedded, agent-controllable app talks to the Skaile platform gateway over
 * a dedicated back-connection — a *different* surface from the agent protocol
 * (`ClientTransport` / `ServerTransport` in `@skaile/workspaces/types`, which are
 * typed to `AgentCommand` / `AgentEvent`). This channel carries only the app
 * handshake plus the capability messages, so it gets its own small, decoupled
 * transport interface. The SDK depends on {@link AppTransport}, never on a
 * concrete socket, so tests inject a fake and the SDK stays browser-safe.
 *
 * The capability message *shapes* are reused verbatim from
 * `@skaile/workspaces/types` — no new capability wire types are introduced.
 * Only the connection handshake (`app_hello` / `app_hello_ack` /
 * `app_hello_nack`) is new, and it is specific to this app↔gateway channel.
 *
 * @category App SDK
 * @since 3.4.0
 */
import type { CapabilityDeregisterCommand, CapabilityInvokedEvent, CapabilityRegisterCommand, CapabilityResultCommand } from "@skaile/workspaces/types";
/**
 * First message an app sends after the socket opens. Declares which app this
 * connection is; the *who* (session identity) is carried out-of-band by the
 * connection's bearer credential (see {@link WebSocketAppTransportOptions}).
 * The gateway binds the authenticated session to `appId` and replies with an
 * {@link AppHelloAckMessage} (or refuses via {@link AppHelloNackMessage}).
 */
export type AppHelloMessage = {
    type: "app_hello";
    /** The embedded app's stable id — bound to the authenticated session. */
    appId: string;
    /** Protocol version string the SDK speaks (see `PROTOCOL_VERSION_STRING`). */
    protocolVersion: string;
};
/** Gateway acknowledgement that the app connection is bound and trusted. */
export type AppHelloAckMessage = {
    type: "app_hello_ack";
    /** The session this app connection is bound to. */
    sessionId: string;
    /** The session's owning user, when the gateway chooses to surface it. */
    userId?: string;
};
/** Gateway refusal — identity could not be verified or `appId` is not permitted. */
export type AppHelloNackMessage = {
    type: "app_hello_nack";
    /** Human-readable reason (also surfaced to the app author). */
    error: string;
    /**
     * Whether another attempt could succeed. `true` means the refusal is transient
     * — the session's agent container is not up yet, and the app raced it on boot.
     * Absent or `false` means permanent (bad token, `appId` not permitted): retrying
     * only burns tokens.
     *
     * @since 3.5.0
     */
    retryable?: boolean;
};
/**
 * Messages an app sends to the gateway. The three capability commands are the
 * unchanged wire types from `@skaile/workspaces/types`; `app_hello` is the
 * only channel-specific addition.
 */
export type AppClientMessage = AppHelloMessage | CapabilityRegisterCommand | CapabilityDeregisterCommand | CapabilityResultCommand;
/**
 * Messages the gateway sends to an app: the handshake outcome, then inbound
 * `capability_invoked` events routed from the agent for this app's `side:'app'`
 * capabilities.
 */
export type AppServerMessage = AppHelloAckMessage | AppHelloNackMessage | CapabilityInvokedEvent;
/**
 * The app back-connection transport. Mirrors the shape of the agent
 * `ClientTransport` but is typed to the app channel's message unions. A
 * concrete WebSocket implementation ships as {@link createWebSocketAppTransport};
 * tests supply a fake.
 *
 * @category App SDK
 * @since 3.4.0
 */
export interface AppTransport {
    /** Open the underlying connection. Resolves once the socket is ready. */
    connect(): Promise<void>;
    /** Close the connection and release resources. Idempotent. */
    disconnect(): Promise<void>;
    /** Send a message to the gateway. */
    send(message: AppClientMessage): void;
    /** Subscribe to messages from the gateway. Returns an unsubscribe function. */
    onMessage(handler: (message: AppServerMessage) => void): () => void;
    /** Subscribe to disconnects. Returns an unsubscribe function. */
    onDisconnect(handler: () => void): () => void;
    /** Whether the transport is currently connected. */
    readonly connected: boolean;
}
//# sourceMappingURL=transport.d.ts.map