@cavi-ai/api-client/core/gateway

export type ActivityEvent = GatewayActivityEvent;

export type ActivityFilters = GatewayActivityFilters;

export declare const AGENT_PROFILE_CONFIG_CONTRACT = "AGENT_PROFILE_CONFIG_V1";

export declare const AGENT_PROFILE_CONFIG_PATCH_CONTRACT = "AGENT_PROFILE_CONFIG_PATCH_V1";

/**
 * Gateway-agnostic chat slash-command + mention parsing.
 *
 * The authoritative command catalog is owned by the gateway and surfaced on the
 * capabilities snapshot (`capabilities.commands`). Use {@link extractGatewayCommandCatalog}
 * to read it and pass the result as the `coreCommands` option so built-ins stay
 * dynamic rather than manually maintained. {@link FALLBACK_CORE_SLASH_COMMANDS}
 * is an offline-only safety net used when the gateway snapshot is unavailable.
 */
export type AgentCommandShortcut = {
    id: string;
    label: string;
    insert: string;
    description?: string;
};

export type AgentCommandSource = {
    id?: string | null;
    name?: string | null;
    commands?: unknown;
    slashCommands?: unknown;
    slash_commands?: unknown;
    commandRegistry?: unknown;
    command_registry?: unknown;
    routing?: unknown;
    config?: unknown;
    snapshot?: unknown;
    orchestration?: unknown;
    triggers?: readonly unknown[] | null;
};

export type AgentCommandSurface = {
    slashShortcuts: AgentCommandShortcut[];
    mentionChips: AgentMentionSuggestion[];
};

export type AgentConfig = {
    agentId: string;
    agentName: string;
    sourcePath?: string;
    etag?: string;
    sections: readonly AgentConfigSection[];
    voice?: AgentVoiceConfig;
    fetchedAt: number;
};

export type AgentConfigDraftDiff = Record<string, AgentConfigFieldValue>;

export type AgentConfigField = {
    key: string;
    label: string;
    description?: string;
    kind: AgentConfigFieldKind;
    value: AgentConfigFieldValue;
    editable?: boolean;
    sourcePath?: readonly string[];
};

export type AgentConfigFieldKind = {
    type: "text";
    placeholder?: string;
} | {
    type: "multiline";
    placeholder?: string;
    minRows?: number;
} | {
    type: "number";
    min?: number;
    max?: number;
    step?: number;
} | {
    type: "toggle";
} | {
    type: "select";
    options: readonly {
        value: string;
        label: string;
    }[];
} | {
    type: "chips";
    suggestions?: readonly string[];
} | {
    type: "list";
    placeholder?: string;
    suggestions?: readonly string[];
} | {
    type: "json";
    minRows?: number;
};

export type AgentConfigFieldValue = string | number | boolean | null | readonly unknown[] | Record<string, unknown>;

export type AgentConfigSection = {
    id: AgentConfigSectionId;
    label: string;
    fields: readonly AgentConfigField[];
};

export type AgentConfigSectionId = string;

export type AgentMentionSuggestion = {
    id: string;
    label: string;
    insert: string;
};

export type AgentProfileConfigPatchBody = {
    contract: typeof AGENT_PROFILE_CONFIG_PATCH_CONTRACT;
    version: 1;
    agentId: string;
    profile: string;
    source: "profile-config-yaml";
    sourcePath: string;
    patch: AgentConfigDraftDiff;
    baseEtag?: string;
};

export declare function agentProfileConfigPath(agentId: string): string;

export declare function agentProfileConfigSourcePath(agentId: string): string;

export type AgentProfileSourcePathResolver = (agentId: string) => string;

export type AgentProfileSummary = {
    agentId: string;
    agentName: string;
    sourcePath?: string;
    isActive?: boolean;
    isDefault?: boolean;
    model?: string | null;
    provider?: string | null;
};

export type AgentRun = {
    key: string;
    title: string;
    agentId: string;
    channel: string;
    updatedAt: number | null;
    status: AgentRunStatus;
    totalTokens: number;
    errors: number;
    /** Model used for this run (e.g. claude-sonnet-4, gpt-4). From backend when available. */
    model?: string;
    /** Cost in USD for this run. From backend when available. */
    totalCostUsd?: number;
    /** Optional manifest-derived binding for source/channel/team routing diagnostics. */
    binding?: GatewayResolvedRouteBinding | null;
};

export type AgentRunDetailSnapshot = {
    run: AgentRun | null;
    preview: {
        status: string;
        items: AgentRunPreviewItem[];
    };
    usage: {
        totalTokens: number;
        totalCostUsd: number;
        messages: number;
        toolCalls: number;
        errors: number;
    };
};

export type AgentRunPreviewItem = {
    role: string;
    text: string;
    at: number | null;
    eventType?: string;
    toolName?: string;
    durationMs?: number | null;
    error?: string | null;
};

export type AgentRunsFilters = {
    search: string;
    activeMinutes: number;
    limit: number;
};

export type AgentRunStatus = "active" | "idle" | "stalled" | "error";

/**
 * Pure parsing for the `tts` block inside a raw agent config payload. Tolerates
 * both snake_case (native YAML) and camelCase (gateway serialisation); every
 * field is optional and the parser is fully defensive against missing data.
 */
/** Voice capabilities for a single TTS provider as configured for this agent. */
export type AgentTtsProviderVoice = {
    provider: string;
    isActive: boolean;
    voiceId: string | null;
    model: string | null;
    extras?: Record<string, string | number>;
};

/** Aggregated voice configuration for an agent, parsed from its raw config payload. */
export type AgentVoiceConfig = {
    activeProvider: string | null;
    voices: AgentTtsProviderVoice[];
};

export declare function asNumber(value: unknown): number | null;

export declare function assertAgentProfileId(agentId: string): string;

export declare function asString(value: unknown): string | null;

export declare function base64UrlDecode(input: string): Uint8Array;

export declare function base64UrlEncode(buf: Uint8Array): string;

export declare const BASELINE_SESSIONS_LIST_PARAMS: SessionsListRequestParams;

export declare function buildAgentCommandSurface(agent: AgentCommandSource | null | undefined, options?: BuildAgentSlashShortcutsOptions): AgentCommandSurface;

export declare function buildAgentConfigFromConfigSnapshot(input: {
    agentId: string;
    config: unknown;
    schema?: unknown;
    defaults?: unknown;
    profile?: AgentProfileSummary | null;
    defaultSourcePath?: AgentProfileSourcePathResolver;
    fetchedAt?: number;
    etag?: string;
}): AgentConfig;

export declare function buildAgentMentionChips(agent: AgentCommandSource | null | undefined): AgentMentionSuggestion[];

export declare function buildAgentProfileConfigPatchBody(params: {
    agentId: string;
    diff: AgentConfigDraftDiff;
    baseEtag?: string;
    sourcePath?: string;
    defaultSourcePath?: AgentProfileSourcePathResolver;
}): AgentProfileConfigPatchBody;

export declare function buildAgentSlashShortcuts(agent: AgentCommandSource | null | undefined, options?: BuildAgentSlashShortcutsOptions): AgentCommandShortcut[];

export type BuildAgentSlashShortcutsOptions = {
    /** Gateway built-ins (from {@link extractGatewayCommandCatalog}); defaults to the offline fallback. */
    coreCommands?: readonly AgentCommandShortcut[];
};

export declare function buildDeviceAuthPayloadV3(params: {
    deviceId: string;
    clientId: string;
    clientMode: string;
    role: string;
    scopes: string[];
    signedAtMs: number;
    token: string;
    nonce: string;
    platform?: string | null;
    deviceFamily?: string | null;
}): string;

export declare function buildGatewayAuthHeaders(clientId: string, authToken: string | null, options?: {
    includeBearerToken?: boolean;
}): Record<string, string>;

export declare function buildIncidentsSnapshot(logs: LogsTailPayload, sessions: RawSessionRow[]): GatewayIncidentsSnapshot;

export declare function buildOverviewSnapshot(sessions: RawSessionRow[], usage: SessionsUsagePayload, readiness: ReadinessInput, options?: BuildOverviewSnapshotOptions): GatewayOverviewSnapshot;

export type BuildOverviewSnapshotOptions = {
    totalSessions?: number;
};

export declare function buildRoutingMatrix(usage: SessionsUsagePayload): GatewayRoutingMatrixSnapshot;

export declare function buildRunDetailSnapshot(run: GatewaySessionRun | null, usageSession: RawUsageSession | null, preview: PreviewItem | null | undefined): GatewaySessionRunDetailSnapshot;

export declare function buildRunsSnapshot(rows: RawSessionRow[], usage: SessionsUsagePayload): GatewaySessionRunsSnapshot;

export declare function canonicalizeSessionDetailParams(params: {
    key?: unknown;
    previewLimit?: unknown;
    maxChars?: unknown;
}): string;

export declare function canonicalizeSessionsListParams(params: SessionsListRequestParams): string;

export declare function canonicalizeSessionsPreviewParams(params: {
    keys?: unknown;
    limit?: unknown;
    maxChars?: unknown;
}): string;

export declare function canonicalizeSessionsUsageParams(params: Record<string, unknown>): string;

export declare function classifyFallbackError(error: unknown): {
    message: string;
    reason: ContractGapReason;
    httpStatus?: number;
};

export declare function cleanGatewayErrorText(value: unknown): string | null;

/**
 * Fan a single subscription out to multiple providers. Events from each
 * provider are forwarded to the shared handler in arrival order; disposing the
 * composite disposes every child subscription. Errors from any child are
 * surfaced via {@link RunEventStreamHandlers.onError}; the others keep running
 * unless the consumer disposes.
 */
export declare function composeRunEventProviders(...providers: RunEventStreamProvider[]): RunEventStreamProvider;

export type ConnectivityDomain = {
    domain: string;
    label: string;
    transport: "ws" | "http" | "mixed";
    source: DataSourceMode | "not-loaded";
    status: ConnectivityStatus;
    contractGaps: readonly ContractGap[];
    fetchedAt: number | null;
};

export type ConnectivityStatus = "live" | "empty-but-valid" | "mock-fallback" | "conditional-unavailable" | "not-loaded";

export type ContractGap = {
    area: string;
    expectedContract: string;
    note: string;
    reason?: ContractGapReason;
    httpStatus?: number;
};

export type ContractGapReason = "backend-unavailable" | "backend-not-configured" | "endpoint-not-found" | "auth-insufficient" | "transport-disconnected" | "unknown";

export type CostBucket = GatewayCostBucket;

export type CostHistoryFilters = GatewayCostHistoryFilters;

export type CostHistoryRange = GatewayCostHistoryRange;

export type CostHistorySnapshot = GatewayCostHistorySnapshot;

export declare function createDemoGatewayCostHistorySnapshot(range: GatewayCostHistoryRange, now?: number): GatewayCostHistorySnapshot;

export declare function createDemoGatewaySnapshotFallbackProvider(now?: number): GatewaySnapshotFallbackProvider;

export declare function createDemoGatewaySnapshotFallbacks(now?: number): GatewaySnapshotFallbacks;

export declare function createEmptyGatewayCostHistorySnapshot(range: GatewayCostHistoryRange): GatewayCostHistorySnapshot;

export declare function createEmptyGatewayIncidentsSnapshot(): GatewayIncidentsSnapshot;

export declare function createEmptyGatewayOverviewSnapshot(now?: number): GatewayOverviewSnapshot;

export declare function createEmptyGatewayRoutingMatrixSnapshot(): GatewayRoutingMatrixSnapshot;

export declare function createEmptyGatewayRunDetailSnapshot(key: string): GatewaySessionRunDetailSnapshot;

export declare function createEmptyGatewayRunsSnapshot(): GatewaySessionRunsSnapshot;

export declare function createEmptyGatewaySnapshotFallbackProvider(): GatewaySnapshotFallbackProvider;

export declare function createEmptyGatewaySnapshotFallbacks(): GatewaySnapshotFallbacks;

export declare function createGatewayAgentConfigClient(clientOptions: HttpApiClientOptions, providerOptions?: ResolveGatewayProviderOptions): GatewayAgentConfigApiClient;

export declare function createGatewayApiClient(clientOptions: HttpApiClientOptions, providerOptions?: ResolveGatewayProviderOptions): GatewayApiClient;

export declare function createGatewayMediaClient(clientOptions: HttpApiClientOptions, providerOptions?: ResolveGatewayProviderOptions): GatewayMediaApiClient;

export declare function createGatewayProviderRegistry(options?: CreateGatewayProviderRegistryOptions): GatewayProviderRegistry;

export type CreateGatewayProviderRegistryOptions = CreateProviderRegistryOptions<GatewayProviderModule>;

export declare const createGatewayRpcClient: typeof createGatewayWebSocketClient;

export declare function createGatewayRpcConnectParams(params: {
    authToken: string | null;
    userAgent: string;
    locale: string;
    options?: GatewayRpcClientOptions;
    device?: {
        id: string;
        publicKey: string;
        signature: string;
        signedAt: number;
        nonce: string;
    } | null;
}): Record<string, unknown>;

export declare function createGatewaySnapshotLoaders(deps: {
    sessionLoaders: SessionLoaders;
    systemLoaders: GatewaySystemLoaders;
    options?: CreateGatewaySnapshotLoadersOptions;
}): GatewaySnapshotLoaders;

export type CreateGatewaySnapshotLoadersOptions = {
    fallbacks?: GatewaySnapshotFallbacks | null;
    fallbackProvider?: GatewaySnapshotFallbackProvider | null;
    resolveBinding?: GatewaySnapshotBindingResolver | null;
};

export declare function createGatewaySseRunEventProvider(options: CreateGatewaySseRunEventProviderOptions, providerOptions?: ResolveGatewayProviderOptions): GatewaySseRunEventProvider;

export type CreateGatewaySseRunEventProviderOptions = GatewaySseRunEventProviderOptions & {
    sessionKey?: string;
};

export declare function createGatewaySystemLoaders(client: GatewayRpcClient | null | undefined): GatewaySystemLoaders;

export declare function createGatewayWebSocketClient(wsUrl: string, authToken: string | null, clientOptions?: GatewayWebSocketClientOptions, providerOptions?: ResolveGatewayProviderOptions): GatewayWebSocketClient;

export declare function createGatewayWikiClient(clientOptions: HttpApiClientOptions, providerOptions?: ResolveGatewayProviderOptions): GatewayWikiApiClient;

export declare function createProviderRegistry<M extends RuntimeProviderModule>(options?: CreateProviderRegistryOptions<M>): ProviderRegistry<M>;

export type CreateProviderRegistryOptions<M extends RuntimeProviderModule = GatewayProviderModule> = CreateRuntimeProviderRegistryOptions<M>;

/**
 * Wraps a primary {@link RunEventStreamProvider} with a tool-event fallback
 * that fires only when the primary's run completes without ever emitting tool
 * events. Used to bridge the gap while the Hermes SSE protocol does not yet
 * surface `tool.call.*` events natively: the
 * {@link RunPreviewPollProvider}-backed fallback stitches tool events in from
 * the post-hoc run preview. When the primary starts emitting tool events
 * natively, the fallback becomes a no-op automatically.
 */
export declare function createRunStreamWithToolFallback(options: CreateRunStreamWithToolFallbackOptions): RunEventStreamProvider;

export type CreateRunStreamWithToolFallbackOptions = {
    /** Authoritative source for lifecycle + (eventually) tool events. */
    primary: RunEventStreamProvider;
    /**
     * One-shot fallback that fires only after the primary emits `run.completed`
     * AND the primary did not emit any tool events during the run. Typically a
     * {@link RunPreviewPollProvider}. Optional — when omitted the composer
     * behaves like `primary` alone.
     */
    toolEventFallback?: RunEventStreamProvider;
};

export declare function createRuntimeProviderRegistry(options?: CreateProviderRegistryOptions<RuntimeProviderModule>): ProviderRegistry<RuntimeProviderModule>;

/**
 * Build the sessions loader bundle. Each call returns a fresh closure with its own caches —
 * intended to be created once per app shell (web adapter, mobile gateway query context) and
 * shared across all queries on that surface.
 */
export declare function createSessionLoaders(client: GatewayRpcClient | null | undefined, options?: CreateSessionLoadersOptions): SessionLoaders;

export type CreateSessionLoadersOptions = {
    /** REST fallback used when the dashboard JSON-RPC websocket is unavailable. */
    requestJson?: SessionHttpRequestJson | null;
};

export type DataEnvelope<TData> = {
    data: TData;
    source: DataSourceMode;
    fetchedAt: number;
    contractGaps: ContractGap[];
};

export type DataSourceMode = "gateway" | "mock";

export declare const DEFAULT_GATEWAY_PROTOCOL_VERSION = 4;

/**
 * Keep token-only connect fallback strictly before the gateway pre-auth
 * handshake timeout. Core owns the timing math; providers and host apps own
 * gateway-specific env keys or explicit timeout overrides.
 */
export declare const DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS = 10000;

export declare function deriveDeviceId(publicKeyRaw: Uint8Array): Promise<string>;

export type DerivedRpcMethodTable<TManifest extends ProviderManifest> = {
    readonly [K in keyof TManifest["rpc"]]: TManifest["rpc"][K]["method"];
};

export declare function deriveRunStatus(run: GatewaySessionRun): GatewaySessionRunStatus;

export type DeviceIdentity = {
    deviceId: string;
    privateKey: CryptoKey;
    publicKeyBase64Url: string;
};

export declare const EMPTY_SESSIONS_USAGE: SessionsUsagePayload;

export declare function exportPublicKeyRaw(key: CryptoKey): Promise<Uint8Array>;

/**
 * Read the gateway built-in command catalog from a capabilities snapshot
 * (`capabilities.commands`). Returns an empty list when the gateway has not
 * surfaced a catalog yet, so callers can decide whether to fall back.
 */
export declare function extractGatewayCommandCatalog(capabilities: unknown): AgentCommandShortcut[];

export declare function extractGatewayErrorDetails(payload: unknown): {
    message: string | null;
    code: string | null;
};

export declare function extractLogIncident(line: string): {
    severity: GatewayIncidentRecord["severity"];
    title: string;
} | null;

/**
 * Offline-only fallback for the gateway built-in slash commands. The live
 * catalog comes from {@link extractGatewayCommandCatalog}; this is only used
 * when the capabilities snapshot has not been fetched yet.
 */
export declare const FALLBACK_CORE_SLASH_COMMANDS: readonly AgentCommandShortcut[];

export declare function fallbackGap(area: string, expectedContract: string, note: string, reason?: ContractGapReason, httpStatus?: number): ContractGap;

export type FallbackResolveInfo = {
    source: "gateway" | "mock";
    fellBack: boolean;
    area: string;
};

export declare function fetchGatewayBlob(path: string, options: GatewayHttpFetchOptions): Promise<Blob>;

export declare function fetchGatewayExpectOk(path: string, options: GatewayHttpFetchOptions): Promise<void>;

export declare function fetchGatewayFormDataJson<T>(path: string, options: Omit<GatewayHttpFetchOptions, "body" | "method"> & {
    body: FormData;
}): Promise<T>;

export declare function fetchGatewayJson<T>(path: string, options: GatewayHttpFetchOptions): Promise<T>;

export declare function findAgentProfile(profiles: readonly AgentProfileSummary[], agentId: string): AgentProfileSummary | null;

export declare function formatGatewayHttpErrorMessage(params: {
    label: string;
    status: number;
    statusText: string;
    message?: string | null;
    code?: string | null;
}): string;

export declare const GATEWAY_JOB_SUCCESS_STATUSES: readonly [
    "completed",
    "succeeded",
    "success"
];

export declare const GATEWAY_JOB_TERMINAL_STATUSES: readonly [
    "completed",
    "succeeded",
    "success",
    "failed",
    "error",
    "cancelled",
    "canceled",
    "stopped"
];

export declare const GATEWAY_MEDIA_ACCEPT_HEADERS: {
    readonly audio: "audio/*";
    readonly image: "image/*";
    readonly video: "video/*";
    readonly music: "audio/*";
};

export declare const GATEWAY_MEDIA_KINDS: readonly [
    "audio",
    "image",
    "video",
    "music"
];

export declare const GATEWAY_PREAUTH_HANDSHAKE_ENV_KEYS: GatewayPreauthHandshakeEnvKeys;

export declare const GATEWAY_PROVIDER_ENV_KEYS: readonly [
    "CAVI_GATEWAY_PROVIDER",
    "GATEWAY_PROVIDER"
];

export declare const GATEWAY_WIKI_FORMATS: readonly [
    "qmd",
    "markdown",
    "html",
    "pdf",
    "text",
    "json"
];

export type GatewayActivityEvent = {
    id: string;
    receivedAt: number;
    type: string;
    agentId: string | null;
    sessionKey: string | null;
    summary: string;
    raw: unknown;
};

export type GatewayActivityFilters = {
    search: string;
    eventTypes: string[];
};

export declare class GatewayAgentConfigApiClient extends BaseHttpApiClient implements GatewayAgentConfigClient {
    readonly endpoints: GatewayAgentConfigEndpointMap;
    protected readonly defaultSourcePath: AgentProfileSourcePathResolver;
    constructor(options: HttpApiClientOptions, configOptions?: GatewayAgentConfigApiClientOptions);
    listProfiles(): Promise<AgentProfileSummary[]>;
    getProfileConfig(agentId: string): Promise<AgentConfig>;
    patchProfileConfig(agentId: string, diff: AgentConfigDraftDiff, options?: PatchProfileConfigOptions): Promise<AgentConfig>;
}

export type GatewayAgentConfigApiClientOptions = {
    endpoints?: GatewayAgentConfigEndpointMap;
    surface?: string;
    defaultSourcePath?: AgentProfileSourcePathResolver;
};

export declare class GatewayAgentConfigApiError extends Error {
    readonly status?: number;
    readonly path?: string;
    constructor(message: string, options?: {
        status?: number;
        path?: string;
    });
}

export interface GatewayAgentConfigClient {
    listProfiles(): Promise<AgentProfileSummary[]>;
    getProfileConfig(agentId: string): Promise<AgentConfig>;
    patchProfileConfig(agentId: string, diff: AgentConfigDraftDiff, options?: PatchProfileConfigOptions): Promise<AgentConfig>;
}

export type GatewayAgentConfigEndpointMap = {
    profiles: string;
    config: string;
    configDefaults: string;
    configSchema: string;
    agentConfigs: string;
    agentConfig: (agentId: string) => string;
};

export declare class GatewayApiClient extends BaseHttpApiClient implements RuntimeClient {
    readonly endpoints: {
        readonly health: "/health";
        readonly healthDetailed: "/health/detailed";
        readonly models: "/v1/models";
        readonly capabilities: "/v1/capabilities";
        readonly chatCompletions: "/v1/chat/completions";
        readonly responses: "/v1/responses";
        readonly response: (responseId: string) => string;
        readonly runs: "/v1/runs";
        readonly run: (runId: string) => string;
        readonly runEvents: (runId: string) => string;
        readonly runApproval: (runId: string) => string;
        readonly runStop: (runId: string) => string;
        readonly jobs: "/api/jobs";
        readonly job: (jobId: string) => string;
    };
    readonly request: HttpApiTransport;
    constructor(options: HttpApiClientOptions, surface?: string);
    getCapabilities(): Promise<GatewayCapabilities>;
    getFeatureCapabilities(options?: Omit<NormalizeGatewayFeatureCapabilitiesOptions, "capabilities">): Promise<NormalizedGatewayFeatureCapabilities>;
    getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
    cancelRun(runId: string): Promise<{
        status: string;
    }>;
    startRun(body: GatewayRunStartBody): Promise<GatewayRunStatus>;
    getRun(runId: string): Promise<GatewayRunStatus>;
    private withNormalizedUsage;
    stopRun(runId: string): Promise<{
        status: string;
    }>;
    resolveRunApproval<T = unknown>(runId: string, body: {
        approved: boolean;
        reason?: string;
    }, idempotencyKey?: string): Promise<T>;
}

export type GatewayCapabilities = GatewayCommandCapabilities & {
    object?: string;
    platform?: string;
    model?: string;
    auth?: {
        type?: string;
        required?: boolean;
    };
    features: Record<string, unknown>;
    endpoints?: Record<string, {
        method: string;
        path: string;
    }>;
    runtime?: Record<string, unknown>;
};

export type GatewayCommandCapabilities = {
    commands?: GatewayCommandCatalog;
    slashCommands?: GatewayCommandCatalog;
    slash_commands?: GatewayCommandCatalog;
    commandCatalog?: GatewayCommandCatalog;
    command_catalog?: GatewayCommandCatalog;
};

export type GatewayCommandCatalog = readonly (GatewayCommandSpec | string)[] | {
    commands?: unknown;
    slashCommands?: unknown;
    slash_commands?: unknown;
    core?: unknown;
    agent?: unknown;
    teams?: unknown;
};

/** Shape of a single entry in the gateway capabilities `commands` catalog. */
export type GatewayCommandSpec = {
    command?: string;
    name?: string;
    id?: string;
    insert?: string;
    template?: string;
    description?: string;
    summary?: string;
    help?: string;
    category?: string;
    aliases?: readonly string[];
    params?: readonly Record<string, unknown>[];
    arguments?: readonly Record<string, unknown>[];
    examples?: readonly string[];
    enabled?: boolean;
    source?: string;
    scope?: string;
    metadata?: Record<string, unknown>;
};

export type GatewayConfigSchemaField = {
    type?: string;
    description?: string;
    category?: string;
    options?: readonly unknown[];
    min?: number;
    max?: number;
    step?: number;
};

export type GatewayConfigSchemaPayload = {
    fields?: Record<string, GatewayConfigSchemaField | unknown>;
    category_order?: readonly string[];
};

export type GatewayConnectionState = "idle" | "connecting" | "reconnecting" | "connected" | "error";

export type GatewayCostBucket = {
    timestamp: number;
    activeSessions: number;
    totalTokens: number;
    estimatedCostUsd: number;
    totalErrors: number;
    providerBreakdown: Array<{
        provider: string;
        tokens: number;
        cost: number;
    }>;
};

export type GatewayCostHistoryFallback = GatewayCostHistorySnapshot | ((range: GatewayCostHistoryRange) => GatewayCostHistorySnapshot);

export type GatewayCostHistoryFilters = {
    range: GatewayCostHistoryRange;
};

export type GatewayCostHistoryRange = "1h" | "6h" | "24h" | "7d";

export type GatewayCostHistorySnapshot = {
    range: GatewayCostHistoryRange;
    resolution: string;
    generatedAt: number;
    buckets: GatewayCostBucket[];
    totals: {
        totalTokens: number;
        estimatedCostUsd: number;
        totalErrors: number;
    };
};

export type GatewayFeatureCapabilityInput = GatewayCapabilities | NormalizedGatewayFeatureCapabilities | null | undefined;

export type GatewayHealthSnapshot = {
    live: boolean;
    ready: boolean;
    checkedAt: number;
    probes: {
        healthz: {
            path: typeof GATEWAY_PROBE_ENDPOINTS.healthz;
            ok: boolean;
            statusCode: 200;
        };
        readyz: {
            path: typeof GATEWAY_PROBE_ENDPOINTS.readyz;
            ok: boolean;
            statusCode: 200 | 503;
            failing: string[];
            uptimeMs: number | null;
        };
    };
};

export type GatewayHttpFetchOptions = Omit<RequestInit, "headers"> & {
    httpBaseUrl: string;
    clientId: string;
    authToken: string | null;
    /** Shown in thrown errors, e.g. "Gateway API". */
    apiLabel: string;
    headers?: Record<string, string>;
    sessionAuthMode?: boolean;
    surface?: HttpApiTrace["surface"];
    fetchImpl?: typeof fetch;
};

export type GatewayIncidentRecord = {
    id: string;
    title: string;
    summary: string;
    severity: GatewayIncidentSeverity;
    status: GatewayIncidentStatus;
    firstSeenAt: number;
    lastSeenAt: number;
    count: number;
    owner: string;
    repeatedAcrossAgents?: boolean;
    flaggedForImmediateFix?: boolean;
    planningRelated?: boolean;
    workTaskAssigned?: string;
    scope?: string;
    agentIds?: string[];
};

export type GatewayIncidentSeverity = "critical" | "high" | "medium" | "low";

export type GatewayIncidentsSnapshot = {
    incidents: GatewayIncidentRecord[];
    blockers: GatewayIncidentRecord[];
};

export type GatewayIncidentStatus = "open" | "investigating" | "blocked" | "resolved";

export declare class GatewayJobAbortError extends Error {
    readonly name = "GatewayJobAbortError";
    readonly reason: unknown;
    constructor(reason?: unknown);
}

export type GatewayJobLike = {
    status?: GatewayJobStatus | null;
    error?: unknown;
};

export type GatewayJobSleep = (delayMs: number, signal?: AbortSignal) => Promise<void>;

export type GatewayJobStatus = "queued" | "running" | "completed" | "succeeded" | "failed" | "cancelled" | "canceled" | "stopping" | "stopped" | string;

export declare class GatewayJobTimeoutError<TJob extends GatewayJobLike> extends Error {
    readonly name = "GatewayJobTimeoutError";
    readonly attempts: number;
    readonly elapsedMs: number;
    readonly lastJob: TJob | null;
    constructor(params: {
        attempts: number;
        elapsedMs: number;
        lastJob: TJob | null;
    });
}

export type GatewayJobWaitOptions<TJob extends GatewayJobLike> = {
    fetchJob: () => Promise<TJob>;
    intervalMs?: number;
    timeoutMs?: number;
    maxAttempts?: number;
    signal?: AbortSignal;
    onUpdate?: (update: GatewayJobWaitUpdate<TJob>) => void;
    isTerminal?: (job: TJob) => boolean;
    sleep?: GatewayJobSleep;
    now?: () => number;
};

export type GatewayJobWaitUpdate<TJob extends GatewayJobLike> = {
    attempt: number;
    elapsedMs: number;
    job: TJob;
};

export declare class GatewayMediaApiClient extends BaseHttpApiClient implements GatewayMediaClient {
    readonly endpoints: GatewayMediaEndpointMap;
    constructor(options: HttpApiClientOptions, mediaOptions?: GatewayMediaApiClientOptions);
    listMediaProviders(kind?: GatewayMediaKind | null): Promise<GatewayMediaProviderList>;
    generateMedia(body: GatewayMediaGenerateRequest, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateAudio(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateImage(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateVideo(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateMusic(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateTextToSpeech(body: GatewayTextToSpeechRequest, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    getMediaJob(kind: GatewayMediaKind, jobId: string): Promise<GatewayMediaGenerationResult>;
    waitForMediaJob(kind: GatewayMediaKind, jobId: string, options?: GatewayMediaJobWaitOptions): Promise<GatewayMediaGenerationResult>;
    listMediaAssets(options?: GatewayMediaAssetListOptions): Promise<GatewayMediaAssetList>;
    getMediaAssetMetadata(assetId: string): Promise<GatewayMediaAsset>;
    createMediaAsset(body: GatewayMediaAssetUploadRequest, idempotencyKey?: string): Promise<GatewayMediaAsset>;
    uploadMediaAsset(body: GatewayMediaAssetUploadRequest, idempotencyKey?: string): Promise<GatewayMediaAsset>;
    deleteMediaAsset(assetId: string): Promise<GatewayMediaAssetDeleteResult>;
    getMediaAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getAudioAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getImageAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getVideoAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getMusicAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
}

export type GatewayMediaApiClientOptions = {
    endpoints?: GatewayMediaEndpointMap;
    surface?: string;
};

export type GatewayMediaAsset = {
    id?: string;
    kind?: GatewayMediaKind | string;
    contentType?: string;
    filename?: string;
    path?: string;
    url?: string;
    size?: number;
    metadata?: Record<string, unknown>;
};

export type GatewayMediaAssetDeleteResult = {
    object?: string;
    id?: string;
    assetId?: string;
    deleted?: boolean;
    status: string;
    metadata?: Record<string, unknown>;
};

export type GatewayMediaAssetList = {
    object?: string;
    kind?: GatewayMediaKind | string;
    assets: readonly GatewayMediaAsset[];
    nextCursor?: string | null;
    metadata?: Record<string, unknown>;
};

export type GatewayMediaAssetListOptions = {
    kind?: GatewayMediaKind | string | null;
    cursor?: string | null;
    limit?: number | null;
};

export type GatewayMediaAssetRequest = Pick<HttpApiRequestInit, "cache" | "credentials" | "headers" | "signal" | "timeoutMs"> & {
    accept?: string;
};

export type GatewayMediaAssetUploadRequest = {
    kind: GatewayMediaKind | string;
    input?: string;
    filename?: string;
    contentType?: string;
    dataBase64?: string;
    url?: string;
    size?: number;
    options?: Record<string, GatewayMediaJsonValue>;
    metadata?: Record<string, unknown>;
};

export type GatewayMediaCapabilityMap = Record<GatewayMediaKind, boolean>;

export interface GatewayMediaClient {
    listMediaProviders(kind?: GatewayMediaKind | null): Promise<GatewayMediaProviderList>;
    generateMedia(body: GatewayMediaGenerateRequest, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateAudio(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateImage(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateVideo(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateMusic(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateTextToSpeech(body: GatewayTextToSpeechRequest, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    getMediaJob(kind: GatewayMediaKind, jobId: string): Promise<GatewayMediaGenerationResult>;
    waitForMediaJob(kind: GatewayMediaKind, jobId: string, options?: GatewayMediaJobWaitOptions): Promise<GatewayMediaGenerationResult>;
    listMediaAssets(options?: GatewayMediaAssetListOptions): Promise<GatewayMediaAssetList>;
    getMediaAssetMetadata(assetId: string): Promise<GatewayMediaAsset>;
    createMediaAsset(body: GatewayMediaAssetUploadRequest, idempotencyKey?: string): Promise<GatewayMediaAsset>;
    uploadMediaAsset(body: GatewayMediaAssetUploadRequest, idempotencyKey?: string): Promise<GatewayMediaAsset>;
    deleteMediaAsset(assetId: string): Promise<GatewayMediaAssetDeleteResult>;
    getMediaAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getAudioAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getImageAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getVideoAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getMusicAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
}

export type GatewayMediaEndpointMap = {
    providers: (kind?: GatewayMediaKind | null) => string;
    generate: (kind: GatewayMediaKind) => string;
    job: (kind: GatewayMediaKind, jobId: string) => string;
    assets: (query?: GatewayMediaAssetListOptions | null) => string;
    asset: (assetId: string) => string;
};

export type GatewayMediaGenerateInput = Omit<GatewayMediaGenerateRequest, "kind">;

export type GatewayMediaGenerateRequest = {
    kind: GatewayMediaKind;
    input: string;
    instructions?: string;
    providerId?: string;
    model?: string;
    voiceId?: string;
    format?: string;
    durationSeconds?: number;
    teamId?: string;
    memberId?: string;
    actionId?: string;
    options?: Record<string, GatewayMediaJsonValue>;
    metadata?: Record<string, unknown>;
};

export type GatewayMediaGenerationResult = {
    object?: string;
    id?: string;
    jobId?: string;
    runId?: string;
    kind?: GatewayMediaKind | string;
    status: "queued" | "running" | "completed" | "failed" | "cancelled" | string;
    asset?: GatewayMediaAsset;
    artifacts?: readonly GatewayMediaAsset[];
    output?: string;
    error?: string;
    metadata?: Record<string, unknown>;
};

export type GatewayMediaJobWaitOptions = Omit<GatewayJobWaitOptions<GatewayMediaGenerationResult>, "fetchJob">;

export type GatewayMediaJsonValue = string | number | boolean | null | readonly GatewayMediaJsonValue[] | {
    readonly [key: string]: GatewayMediaJsonValue;
};

export type GatewayMediaKind = (typeof GATEWAY_MEDIA_KINDS)[number];

export type GatewayMediaProvider = {
    id: string;
    kind?: GatewayMediaKind | string;
    label?: string;
    name?: string;
    configured?: boolean;
    models?: readonly string[];
    voices?: readonly (string | {
        id: string;
        name?: string;
    })[];
    metadata?: Record<string, unknown>;
};

export type GatewayMediaProviderCapabilityInput = GatewayMediaProviderList | readonly GatewayMediaProvider[] | readonly GatewayMediaProviderList[];

export type GatewayMediaProviderList = {
    object?: string;
    kind?: GatewayMediaKind | string;
    providers: readonly GatewayMediaProvider[];
};

export type GatewayOverviewKpis = {
    activeSessions: number;
    totalSessions: number;
    totalMessages: number;
    totalToolCalls: number;
    totalErrors: number;
    estimatedCostUsd: number;
};

export type GatewayOverviewSnapshot = {
    health: GatewayHealthSnapshot;
    kpis: GatewayOverviewKpis;
    providerBreakdown: Array<{
        provider: string;
        tokens: number;
        cost: number;
    }>;
    topAgents: Array<{
        agentId: string;
        messages: number;
        cost: number;
    }>;
};

export type GatewayPreauthHandshakeEnv = Readonly<Record<string, string | undefined>>;

export type GatewayPreauthHandshakeEnvKeys = Readonly<{
    timeoutMs: string;
    testTimeoutMs?: string;
    testFlag?: string;
}>;

export type GatewayProviderEnv = Record<string, string | undefined>;

export interface GatewayProviderFactories {
    createApiClient?: (clientOptions: HttpApiClientOptions) => GatewayApiClient;
    createWebSocketClient?: (wsUrl: string, authToken: string | null, clientOptions: GatewayWebSocketClientOptions) => GatewayWebSocketClient;
    createSseRunEventProvider?: (options: CreateGatewaySseRunEventProviderOptions) => GatewaySseRunEventProvider;
    createMediaClient?: (clientOptions: HttpApiClientOptions) => GatewayMediaApiClient;
    createWikiClient?: (clientOptions: HttpApiClientOptions) => GatewayWikiApiClient;
    createAgentConfigClient?: (clientOptions: HttpApiClientOptions) => GatewayAgentConfigApiClient;
}

export type GatewayProviderKind = "hermes" | "openclaw" | (string & {});

export interface GatewayProviderModule extends RuntimeProviderModule, GatewayProviderFactories {
    /** Gateway providers return the gateway-capable client. */
    createApiClient?: (clientOptions: HttpApiClientOptions) => GatewayApiClient;
}

export type GatewayProviderRegistry = ProviderRegistry<GatewayProviderModule>;

export type GatewayRoutingMatrixSnapshot = {
    rows: Array<{
        channel: string;
        handler: string;
        totalRuns: number;
        successRuns: number;
        failedRuns: number;
        successRate: number;
        messages: number;
        binding?: GatewayResolvedRouteBinding | null;
    }>;
    totals: {
        totalRuns: number;
        successRuns: number;
        failedRuns: number;
    };
};

export declare class GatewayRpcClient {
    private readonly wsUrl;
    private readonly authToken;
    private readonly options;
    private socket;
    private connectPromise;
    private pending;
    private activeRpcRequests;
    private queuedRpcRequests;
    private sequence;
    private connected;
    /** Set when a connect RPC is explicitly rejected (auth failure, etc.) so onClose
     *  does not emit a retryable socket_closed error that triggers an infinite reconnect loop. */
    private connectRejected;
    private eventListeners;
    private stateListeners;
    private state;
    private lastError;
    private intentionalClose;
    private emitRpcTrace;
    private deviceIdentity;
    private deviceIdentityReady;
    /** Incremented on each connect attempt; stale async connect paths must not resolve the outer promise. */
    private connectAttemptSeq;
    constructor(wsUrl: string, authToken: string | null, options?: GatewayRpcClientOptions);
    getConnectionState(): GatewayConnectionState;
    getLastError(): Error | null;
    onEvent(listener: (event: GatewayStreamEvent) => void): () => void;
    onStateChange(listener: (state: GatewayConnectionState, error: Error | null) => void): () => void;
    connect(): Promise<void>;
    request<TPayload>(method: string, params?: Record<string, unknown>): Promise<TPayload>;
    close(): Promise<void>;
    private setState;
    private getConnectClientInfo;
    private ensureConnected;
    private requestRaw;
    private runWithRpcBackpressure;
    private drainQueuedRpcRequests;
    private rejectQueuedRpcRequests;
    private handleMessage;
}

export type GatewayRpcClientOptions = {
    clientId?: string;
    clientVersion?: string;
    clientMode?: string;
    clientPlatform?: string;
    /**
     * Correlation-id strategy for the initial `connect` handshake frame.
     * - `"monotonic"` (default): connect uses the same per-client monotonic id as
     *   every other RPC.
     * - `"client-id"`: connect reuses the advertised `clientId` as its frame id.
     *   Opt into this for gateways that correlate the connect response on the
     *   advertised client id rather than echoing an arbitrary request id.
     * Subsequent (non-connect) RPCs always use monotonic ids regardless.
     */
    connectFrameId?: "monotonic" | "client-id";
    /**
     * Gateway protocol compatibility range to advertise during connect.
     * Defaults to the current generic gateway protocol. Override only when
     * talking to a gateway with a known alternate compatibility contract.
     */
    minProtocol?: number;
    maxProtocol?: number;
    enableDeviceIdentity?: boolean;
    /**
     * Optional platform-specific device identity loader. Browser callers use the
     * built-in IndexedDB/WebCrypto store; React Native callers can provide a
     * SecureStore-backed loader while still using the shared connect signer.
     */
    deviceIdentityLoader?: () => Promise<DeviceIdentity | null>;
    /**
     * Operator scopes to request on connect. Empty/blank entries are ignored.
     * When omitted, defaults to `["operator.read"]` for backwards compatibility;
     * callers needing admin-level methods (e.g. `device.pair.approve`) must opt in
     * explicitly so the gateway does not silently downgrade them to read-only.
     */
    requestedScopes?: readonly string[];
    /**
     * Gateway pre-auth handshake budget (ms). Set this to the same value as server
     * handshake config when it is not the default, especially for browser clients
     * that cannot read gateway env.
     */
    preauthHandshakeTimeoutMs?: number;
    /**
     * Env bag and keys for provider-specific pre-auth handshake config. Core uses
     * GATEWAY_* keys by default; providers can pass their own keys without baking
     * product names into the core client.
     */
    preauthHandshakeEnv?: GatewayPreauthHandshakeEnv;
    preauthHandshakeEnvKeys?: GatewayPreauthHandshakeEnvKeys;
    /** Override the per-RPC response timeout. */
    requestTimeoutMs?: number;
    /** Override client-side RPC concurrency. */
    maxConcurrentRequests?: number;
    /** Override the default requested scopes used when requestedScopes is omitted. */
    defaultRequestedScopes?: readonly string[];
    /**
     * Optional hook for completed RPCs (success, gateway error, timeout, or send failure).
     * Params are redacted; payloads are truncated. Must not throw.
     */
    onRpcTrace?: (entry: GatewayRpcTraceEntry) => void;
};

export declare class GatewayRpcError extends Error {
    readonly type = ApiClientErrorType.GatewayRpc;
    readonly code: string;
    constructor(message: string, code?: string);
}

/** Completed WebSocket RPC (after response or failure). Params are redacted. */
export type GatewayRpcTraceEntry = {
    at: number;
    transport: "websocket";
    correlationId: string;
    method: string;
    durationMs: number;
    ok: boolean;
    params: Record<string, unknown>;
    /** JSON preview of successful payload (bounded). */
    resultPreview?: string;
    /** Populated when `ok` is false. */
    error?: {
        name: string;
        message: string;
        code?: string;
    };
};

export type GatewayRunAttachment = {
    name: string;
    mimeType?: string;
    mime_type?: string;
    size?: number;
    dataBase64?: string;
    data_base64?: string;
    [key: string]: unknown;
};

export type GatewayRunMessage = RuntimeRunMessage;

export type GatewayRunStartBody = RuntimeRunStartBody & {
    session_id?: string;
    sessionKey?: string;
    session_key?: string;
    previous_response_id?: string;
    conversation_history?: GatewayRunMessage[];
    targetProfile?: string;
    target_profile?: string;
    targetAgent?: string;
    target_agent?: string;
    agentId?: string;
    agent_id?: string;
    action?: string;
    source?: Record<string, unknown>;
    attachments?: GatewayRunAttachment[];
    dry_run?: boolean;
};

export type GatewayRunStatus = RuntimeRunStatus & {
    object?: string;
    session_id?: string;
    targetProfile?: string;
    task_id?: string;
    routing?: {
        kind?: string;
        targetProfile?: string | null;
        taskId?: string | null;
        workerEventStream?: boolean;
        decision?: Record<string, unknown>;
    };
    events?: Record<string, unknown>[];
    tool_call_count?: number;
};

export type GatewayScope = "operator.read" | "operator.write" | "operator.admin" | "operator.approvals" | "operator.pairing" | "operator.talk.secrets" | "node" | "dynamic";

export type GatewaySessionRun = {
    key: string;
    title: string;
    agentId: string;
    channel: string;
    updatedAt: number | null;
    status: GatewaySessionRunStatus;
    totalTokens: number;
    errors: number;
    model?: string;
    totalCostUsd?: number;
    binding?: GatewayResolvedRouteBinding | null;
};

export type GatewaySessionRunDetailSnapshot = {
    run: GatewaySessionRun | null;
    preview: {
        status: string;
        items: Array<{
            role: string;
            text: string;
            at: number | null;
            eventType?: string;
            toolName?: string;
            durationMs?: number | null;
            error?: string | null;
        }>;
    };
    usage: {
        totalTokens: number;
        totalCostUsd: number;
        messages: number;
        toolCalls: number;
        errors: number;
    };
};

export type GatewaySessionRunsSnapshot = {
    live: GatewaySessionRun[];
    history: GatewaySessionRun[];
    summary: {
        active: number;
        idle: number;
        stalled: number;
        error: number;
    };
};

export type GatewaySessionRunStatus = "active" | "idle" | "stalled" | "error";

export type GatewaySnapshotBindingInput = {
    key?: string | null;
    sessionKey?: string | null;
    source?: string | null;
    channel?: string | null;
    agentId?: string | null;
    actionId?: string | null;
};

export type GatewaySnapshotBindingResolver = (input: GatewaySnapshotBindingInput) => GatewayResolvedRouteBinding | null;

export type GatewaySnapshotFallbackMode = "none" | "empty" | "demo";

export type GatewaySnapshotFallbackOverrides = Partial<GatewaySnapshotFallbacks> & {
    costHistory?: GatewayCostHistoryFallback | null;
};

export type GatewaySnapshotFallbackProvider = {
    snapshots?: GatewaySnapshotFallbacks | (() => GatewaySnapshotFallbacks);
    costHistory?: GatewayCostHistoryFallback;
};

export type GatewaySnapshotFallbacks = {
    overview: GatewayOverviewSnapshot | (() => GatewayOverviewSnapshot);
    agentRuns: GatewaySessionRunsSnapshot | (() => GatewaySessionRunsSnapshot);
    runDetail: GatewaySessionRunDetailSnapshot | ((key: string) => GatewaySessionRunDetailSnapshot);
    routingMatrix: GatewayRoutingMatrixSnapshot | ((windowDays: number) => GatewayRoutingMatrixSnapshot);
    incidents: GatewayIncidentsSnapshot | (() => GatewayIncidentsSnapshot);
};

export type GatewaySnapshotLoaders = {
    loadOverview: () => Promise<DataEnvelope<GatewayOverviewSnapshot>>;
    loadAgentRuns: (filters: GatewaySnapshotRunFilters) => Promise<DataEnvelope<GatewaySessionRunsSnapshot>>;
    loadRunDetail: (key: string) => Promise<DataEnvelope<GatewaySessionRunDetailSnapshot>>;
    loadRoutingMatrix: (windowDays: number) => Promise<DataEnvelope<GatewayRoutingMatrixSnapshot>>;
    loadIncidents: () => Promise<DataEnvelope<GatewayIncidentsSnapshot>>;
};

export type GatewaySnapshotRunFilters = {
    search: string;
    activeMinutes: number;
    limit: number;
};

export type GatewaySseRunEventEndpointMap = {
    run: (runId: string) => string;
    runEvents: (runId: string) => string;
};

export type GatewaySseRunEventHeaderResolver = (params: {
    runId: string;
    phase: GatewaySseRunEventPhase;
}) => Record<string, string | null | undefined>;

export type GatewaySseRunEventPhase = "events" | "poll";

/**
 * Provider-neutral run-event SSE reader. Generic stream mechanics live in
 * core/sse; this class owns gateway request headers, canonical run-event
 * translation, and status polling fallback. Provider adapters should only
 * supply endpoint maps and any gateway-specific session/routing headers.
 */
export declare class GatewaySseRunEventProvider implements RunEventStreamProvider {
    private readonly httpBase;
    private readonly authToken;
    private readonly clientId;
    private readonly endpoints;
    private readonly headers;
    private readonly resolveHeaders?;
    private readonly fallbackToPoll;
    private readonly pollIntervalMs;
    private readonly pollTimeoutMs;
    private readonly fetchImpl;
    constructor(options: GatewaySseRunEventProviderOptions);
    subscribe(params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
    private buildHeaders;
    private streamEvents;
    private pollUntilTerminal;
}

export type GatewaySseRunEventProviderOptions = {
    httpBase: string;
    authToken: string | null;
    clientId: string;
    endpoints?: GatewaySseRunEventEndpointMap;
    /**
     * Static provider headers. Provider adapters use this for gateway-specific
     * routing/session headers while the base class owns SSE parsing and polling.
     */
    headers?: Record<string, string | null | undefined>;
    /** Dynamic provider headers, resolved separately for the SSE request and poll fallback. */
    resolveHeaders?: GatewaySseRunEventHeaderResolver;
    /**
     * When true (default), falls back to polling the configured run status endpoint on terminal SSE failure modes
     * (404/405/406/501, "stream disabled" 400, non-SSE content-type, missing readable body).
     */
    fallbackToPoll?: boolean;
    pollIntervalMs?: number;
    pollTimeoutMs?: number;
    fetchImpl?: typeof fetch;
};

export type GatewayStreamEvent = {
    event: string;
    payload: unknown;
};

export declare function gatewaySupportsAction(input: GatewayFeatureCapabilityInput, action: string): boolean;

export declare function gatewaySupportsMediaKind(input: GatewayFeatureCapabilityInput, kind: GatewayMediaKind | string): boolean;

export declare function gatewaySupportsRpcMethod(input: GatewayFeatureCapabilityInput, method: string): boolean;

export declare function gatewaySupportsTextToSpeech(input: GatewayFeatureCapabilityInput): boolean;

export type GatewaySystemLoaders = {
    loadHealthSnapshotRaw: () => Promise<HealthSnapshotPayload>;
    loadLogsTailRaw: (params: {
        limit: number;
        maxBytes: number;
    }) => Promise<LogsTailPayload>;
};

export type GatewayTextToSpeechRequest = Omit<GatewayMediaGenerateInput, "input"> & {
    text: string;
};

export declare class GatewayWikiApiClient extends BaseHttpApiClient implements GatewayWikiClient {
    readonly endpoints: GatewayWikiEndpointMap;
    constructor(options: HttpApiClientOptions, wikiOptions?: GatewayWikiApiClientOptions);
    listWikiVaults(): Promise<GatewayWikiVaultList>;
    getWikiVault(vaultId: string): Promise<GatewayWikiVault>;
    getWikiTree(vaultId: string): Promise<GatewayWikiTree>;
    readWikiPage(vaultId: string, path: string): Promise<GatewayWikiPage>;
    ingestWiki(vaultId: string, body: GatewayWikiIngestRequest, idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    compileWiki(vaultId: string, body: GatewayWikiCompileRequest, idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    promoteWiki(vaultId: string, body: GatewayWikiPromoteRequest, idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    getWikiJob(vaultId: string, jobId: string): Promise<GatewayWikiJobResult>;
    getWikiArtifact(vaultId: string, artifactId: string, init?: GatewayWikiArtifactRequest): Promise<Blob>;
}

export type GatewayWikiApiClientOptions = {
    endpoints?: GatewayWikiEndpointMap;
    surface?: string;
};

export type GatewayWikiArtifactRequest = Pick<HttpApiRequestInit, "cache" | "credentials" | "headers" | "signal" | "timeoutMs"> & {
    accept?: string;
};

export interface GatewayWikiClient {
    listWikiVaults(): Promise<GatewayWikiVaultList>;
    getWikiVault(vaultId: string): Promise<GatewayWikiVault>;
    getWikiTree(vaultId: string): Promise<GatewayWikiTree>;
    readWikiPage(vaultId: string, path: string): Promise<GatewayWikiPage>;
    ingestWiki(vaultId: string, body: GatewayWikiIngestRequest, idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    compileWiki(vaultId: string, body: GatewayWikiCompileRequest, idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    promoteWiki(vaultId: string, body: GatewayWikiPromoteRequest, idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    getWikiJob(vaultId: string, jobId: string): Promise<GatewayWikiJobResult>;
    getWikiArtifact(vaultId: string, artifactId: string, init?: GatewayWikiArtifactRequest): Promise<Blob>;
}

export type GatewayWikiCompileRequest = {
    path?: string;
    paths?: readonly string[];
    target?: GatewayWikiFormat | string;
    outputPath?: string;
    options?: Record<string, GatewayWikiJsonValue>;
    metadata?: Record<string, unknown>;
};

export type GatewayWikiEndpointMap = {
    vaults: string;
    vault: (vaultId: string) => string;
    tree: (vaultId: string) => string;
    read: (vaultId: string, path: string) => string;
    ingest: (vaultId: string) => string;
    compile: (vaultId: string) => string;
    promote: (vaultId: string) => string;
    job: (vaultId: string, jobId: string) => string;
    artifact: (vaultId: string, artifactId: string) => string;
};

export type GatewayWikiFormat = (typeof GATEWAY_WIKI_FORMATS)[number];

export type GatewayWikiIngestRequest = {
    path?: string;
    title?: string;
    content?: string;
    sourceUrl?: string;
    sourcePath?: string;
    artifactId?: string;
    format?: GatewayWikiFormat | string;
    tags?: readonly string[];
    frontmatter?: Record<string, GatewayWikiJsonValue>;
    teamId?: string;
    memberId?: string;
    actionId?: string;
    options?: Record<string, GatewayWikiJsonValue>;
    metadata?: Record<string, unknown>;
};

export type GatewayWikiJobResult = {
    object?: string;
    id?: string;
    jobId?: string;
    vaultId?: string;
    path?: string;
    status: "queued" | "running" | "completed" | "failed" | "cancelled" | string;
    artifactId?: string;
    outputPath?: string;
    page?: GatewayWikiPage;
    error?: string;
    metadata?: Record<string, unknown>;
};

export type GatewayWikiJsonValue = string | number | boolean | null | readonly GatewayWikiJsonValue[] | {
    readonly [key: string]: GatewayWikiJsonValue;
};

export type GatewayWikiPage = {
    object?: string;
    vaultId: string;
    path: string;
    title?: string;
    format?: GatewayWikiFormat | string;
    content: string;
    frontmatter?: Record<string, GatewayWikiJsonValue>;
    metadata?: Record<string, unknown>;
};

export type GatewayWikiPromoteRequest = {
    sourcePath?: string;
    targetPath?: string;
    artifactId?: string;
    title?: string;
    status?: string;
    tags?: readonly string[];
    frontmatter?: Record<string, GatewayWikiJsonValue>;
    options?: Record<string, GatewayWikiJsonValue>;
    metadata?: Record<string, unknown>;
};

export type GatewayWikiTree = {
    object?: string;
    vaultId: string;
    entries: readonly GatewayWikiTreeEntry[];
    metadata?: Record<string, unknown>;
};

export type GatewayWikiTreeEntry = {
    path: string;
    kind: "directory" | "file" | string;
    title?: string;
    format?: GatewayWikiFormat | string;
    size?: number;
    updatedAt?: string;
    metadata?: Record<string, unknown>;
};

export type GatewayWikiVault = {
    id: string;
    label?: string;
    pluginId?: string;
    rootPath?: string;
    defaultFormat?: GatewayWikiFormat | string;
    capabilities?: readonly string[];
    metadata?: Record<string, unknown>;
};

export type GatewayWikiVaultList = {
    object?: string;
    vaults: readonly GatewayWikiVault[];
};

export declare function generateDeviceKeypair(): Promise<CryptoKeyPair>;

export declare function getOrCreateTtlCacheEntry<TPayload>(cache: Map<string, TtlCacheEntry<TPayload>>, cacheKey: string): TtlCacheEntry<TPayload>;

export type HealthSnapshot = GatewayHealthSnapshot;

export type HealthSnapshotPayload = {
    ready: boolean;
    failing?: unknown[];
    uptimeMs?: number | null;
};

export type IncidentRecord = GatewayIncidentRecord;

export type IncidentSeverity = GatewayIncidentSeverity;

export type IncidentsSnapshot = GatewayIncidentsSnapshot;

export type IncidentStatus = GatewayIncidentStatus;

export declare function isDeviceIdentitySupported(): boolean;

export declare function isGatewayJobSuccessfulStatus(status: GatewayJobStatus | null | undefined): boolean;

export declare function isGatewayJobTerminalStatus(status: GatewayJobStatus | null | undefined): boolean;

export declare function isMissingAgentConfigRouteError(error: unknown): boolean;

export declare function isUnchangedSessionsListPayload(payload: unknown): payload is SessionsListUnchangedPayload;

export declare function loadOrCreateDeviceIdentity(): Promise<DeviceIdentity | null>;

export type LogsTailPayload = {
    lines?: string[];
};

/** Defaults for React Native while preserving caller-provided client identity. */
export declare function mergeGatewayRpcClientOptionsForReactNative(options?: GatewayRpcClientOptions): GatewayRpcClientOptions;

export declare function mergeGatewaySnapshotFallbacks(base: GatewaySnapshotFallbacks, overrides?: Partial<GatewaySnapshotFallbacks> | null): GatewaySnapshotFallbacks;

export type MutationResult<TData> = {
    data: TData;
    source: DataSourceMode;
    appliedAt: number;
    contractGaps: ContractGap[];
};

export declare function normalizeAgentProfiles(payload: unknown): AgentProfileSummary[];

export type NormalizedGatewayFeatureCapabilities = {
    media: boolean;
    mediaKinds: GatewayMediaCapabilityMap;
    textToSpeech: boolean;
    wiki: boolean;
    sse: boolean;
    websocket: boolean;
    rpc: boolean;
    rpcMethods: readonly string[];
    actions: readonly string[];
    commands: readonly string[];
    rawFeatures: Record<string, unknown>;
};

export type NormalizedGatewayStreamFailure = {
    state: "idle" | "connecting" | "reconnecting" | "connected" | "error";
    error: string | null;
    retryable: boolean;
};

export declare function normalizeGatewayBaseUrl(rawGatewayBaseUrl: string | null | undefined): string | null;

export declare function normalizeGatewayFeatureCapabilities(options?: NormalizeGatewayFeatureCapabilitiesOptions): NormalizedGatewayFeatureCapabilities;

export type NormalizeGatewayFeatureCapabilitiesOptions = {
    capabilities?: GatewayCapabilities | null;
    mediaProviders?: GatewayMediaProviderCapabilityInput | null;
};

export declare function normalizeGatewayProviderToken(value: string | null | undefined): string | null;

/**
 * Classifies stream / RPC failures for reconnect vs hard-error UX.
 * GatewayRpcError codes are checked before substring heuristics on messages.
 */
export declare function normalizeGatewayStreamFailure(error: unknown): NormalizedGatewayStreamFailure;

export declare function normalizeRun(row: RawSessionRow, index: number): GatewaySessionRun;

export declare function normalizeRuntimeProviderToken(value: string | null | undefined): string | null;

export declare function normalizeSessionsListPayload(payload: SessionsListRpcPayload): SessionsListPayloadWithCache;

export type OverviewKpis = GatewayOverviewKpis;

export type OverviewSnapshot = GatewayOverviewSnapshot;

export type ParamSpec = {
    type: string;
    required?: boolean;
    note?: string;
};

export declare function parseAgentVoiceConfig(rawConfig: unknown): AgentVoiceConfig;

export declare function parseGatewayErrorText(text: string, contentType: string): {
    message: string | null;
    code: string | null;
};

export declare function parseGatewayRoutingQuery(searchParams: URLSearchParams): {
    windowDays: number;
};

export declare const parseGatewayRunsQuery: typeof parseGatewaySessionRunsQuery;

export declare function parseGatewaySessionRunsQuery(searchParams: URLSearchParams): {
    search: string;
    activeMinutes: number;
    limit: number;
};

export type PatchProfileConfigOptions = {
    baseEtag?: string;
    sourcePath?: string;
};

/** Optional header some gateways require for audit / routing. */
export declare const PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER: "X-Portal-Client-Id";

/**
 * Shared HTTP contract for portal dashboard config updates (POST).
 * Any client (mobile, web, scripts) may call {@link postPortalConfigPatch} against
 * the portal config surface once the gateway implements the route.
 */
export declare const PORTAL_CONFIG_PATCH_CONTRACT: "PORTAL_CONFIG_PATCH_V1";

export declare const PORTAL_CONFIG_PATCH_CONTRACT_VERSION: 1;

export declare class PortalConfigPatchError extends Error {
    readonly status: number;
    readonly responseBody: string | null;
    constructor(status: number, message: string, responseBody: string | null);
}

export declare function portalConfigPatchPath(portalSlug: string): string;

export type PortalConfigPatchRequestBody = {
    contract: typeof PORTAL_CONFIG_PATCH_CONTRACT;
    v: typeof PORTAL_CONFIG_PATCH_CONTRACT_VERSION;
    /** Gateway-defined scope (e.g. `readiness`, `snapshot.thresholds`). */
    scope: string;
    /** Nested object; build from flat UI keys with {@link unflattenPortalConfigPatchKeys}. */
    patch: Record<string, unknown>;
};

export declare function postPortalConfigPatch(params: PostPortalConfigPatchParams): Promise<unknown>;

export type PostPortalConfigPatchParams = {
    httpBase: string;
    /** Bearer secret without the `Bearer ` prefix. */
    authToken: string;
    /** URL segment only, e.g. `portal-a`. */
    portalSlug: string;
    scope: string;
    patch: Record<string, unknown>;
    /** Sent as {@link PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER} when non-empty. */
    clientId?: string;
    fetchImpl?: typeof fetch;
    signal?: AbortSignal;
};

export type PreviewItem = {
    key?: string;
    status?: string;
    items?: Array<{
        role?: string;
        sender?: string;
        text?: string;
        at?: number;
    }>;
};

export type ProviderEventSpec = {
    name: string;
    family: string;
    payload?: ResponseSpec;
    note?: string;
};

export type ProviderManifest = {
    /** Provider identifier (`openclaw`, `hermes`, …). */
    provider: string;
    /** Manifest revision; bump when the schema or content shape changes. */
    version: string;
    /** Upstream doc location this manifest mirrors. */
    upstream: {
        repo: string;
        path: string;
        note?: string;
    };
    rpc: Readonly<Record<string, ProviderRpcMethod>>;
    rest: Readonly<Record<string, ProviderRestEndpoint>>;
    events: Readonly<Record<string, ProviderEventSpec>>;
};

export type ProviderRegistry<M extends RuntimeProviderModule = GatewayProviderModule> = RuntimeProviderRegistry<M>;

export type ProviderRestEndpoint = {
    /** Surface grouping mirrors the upstream doc's HTTP families. */
    surface: string;
    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
    /** Path template, e.g. `/sessions/:sessionKey/kill`. */
    path: string;
    auth: "none" | "bearer" | "bearer-or-header" | "bearer-loopback" | "plugin-defined";
    status: ProviderRestStatus;
    docSection?: string;
    note?: string;
};

export type ProviderRestStatus = "doc-only" | "live-verified";

export type ProviderRpcMethod = {
    /** Wire method name, e.g. `chat.send`. */
    method: string;
    /** Slug grouping the method, mirrors the upstream doc's section. */
    category: string;
    /** Required scope(s) to invoke. `dynamic` is plugin-resolved per call. */
    scope: GatewayScope | readonly GatewayScope[];
    /** Whether the gateway advertises this method in `hello-ok.features.methods`. */
    advertised: boolean;
    status: ProviderRpcStatus;
    params?: Record<string, ParamSpec>;
    response?: ResponseSpec;
    behavior?: RpcBehaviorSpec;
    /** Stable anchor or section label from the upstream doc (drift detection). */
    docSection?: string;
    note?: string;
};

export type ProviderRpcStatus = "doc-only" | "shape-verified" | "live-verified";

export type RawSessionRow = {
    key?: string;
    label?: string;
    derivedTitle?: string;
    agentId?: string;
    channel?: string;
    updatedAt?: number | null;
    abortedLastRun?: boolean;
    totalTokens?: number;
    origin?: {
        provider?: string;
        surface?: string;
    };
};

export type RawUsageSession = {
    key?: string;
    agentId?: string;
    channel?: string;
    modelProvider?: string;
    model?: string;
    modelOverride?: string;
    providerOverride?: string;
    origin?: {
        provider?: string;
        surface?: string;
    };
    usage?: {
        totalTokens?: number;
        totalCost?: number;
        messageCounts?: {
            total?: number;
            toolCalls?: number;
            errors?: number;
        };
    } | null;
};

export type ReadinessInput = {
    ready: boolean;
    failing: string[];
    uptimeMs: number | null;
    statusCode: 200 | 503;
};

export declare function requestedGatewayProvider(options: ResolveGatewayProviderOptions): string | null;

export declare function requestGatewayRaw(path: string, options: GatewayHttpFetchOptions): Promise<Response>;

/** Delay before sending `connect` without a nonce when device identity is enabled. */
export declare function resolveDeviceTokenOnlyFallbackMs(params?: ResolveDeviceTokenOnlyFallbackMsParams): number;

export type ResolveDeviceTokenOnlyFallbackMsParams = {
    env?: GatewayPreauthHandshakeEnv;
    envKeys?: GatewayPreauthHandshakeEnvKeys;
    /** Explicit gateway handshake budget in milliseconds. */
    preauthHandshakeTimeoutMs?: number;
};

/** Resolved client fields for `connect` and device-auth v3 signing (must stay aligned). */
export type ResolvedGatewayRpcClientProfile = {
    clientId: string;
    clientVersion: string;
    clientPlatform: string;
    clientMode: string;
};

export type ResolvedGatewaySnapshotFallbacks = {
    snapshots: GatewaySnapshotFallbacks | null;
    costHistory: GatewayCostHistoryFallback | null;
};

export declare function resolveGatewayConnectScopes(options?: GatewayRpcClientOptions): string[];

export declare function resolveGatewayProviderKind(options?: ResolveGatewayProviderOptions): GatewayProviderKind;

export declare function resolveGatewayProviderModule(options?: ResolveGatewayProviderOptions): GatewayProviderModule | null;

export type ResolveGatewayProviderOptions = {
    provider?: GatewayProviderKind | string | null;
    env?: GatewayProviderEnv;
    defaultProvider?: GatewayProviderKind | string | null;
    registry?: GatewayProviderRegistry | null;
    providerModules?: readonly GatewayProviderModule[] | null;
    allowProviderOverrides?: boolean;
};

export declare function resolveGatewayRequestCredentials(sessionAuthMode: boolean | null | undefined): RequestCredentials | undefined;

export declare function resolveGatewayRpcClientProfile(options?: GatewayRpcClientOptions): ResolvedGatewayRpcClientProfile;

export declare function resolveGatewayRuntimeHttpBase(gatewayBaseUrl: string, options?: ResolveGatewayRuntimeTargetOptions): string;

export declare function resolveGatewayRuntimeHttpUrl(gatewayBaseUrl: string, pathname: string, options?: ResolveGatewayRuntimeTargetOptions): string;

export type ResolveGatewayRuntimeTargetOptions = {
    configuredGatewayBaseUrl?: string | null;
    windowOrigin?: string | null;
    fallbackWsUrl?: string;
};

export declare function resolveGatewayRuntimeWsUrl(gatewayBaseUrl: string, options?: ResolveGatewayRuntimeTargetOptions): string;

export declare function resolveGatewaySnapshotFallbacks(options?: ResolveGatewaySnapshotFallbacksOptions): ResolvedGatewaySnapshotFallbacks;

export type ResolveGatewaySnapshotFallbacksOptions = {
    mode?: GatewaySnapshotFallbackMode;
    provider?: GatewaySnapshotFallbackProvider | null;
    overrides?: GatewaySnapshotFallbackOverrides | null;
    now?: number;
};

export declare const resolveGatewayTargets: typeof resolveHttpWebSocketTargets;

export declare function resolvePreauthHandshakeTimeoutMs(params?: ResolvePreauthHandshakeTimeoutMsParams): number;

export type ResolvePreauthHandshakeTimeoutMsParams = {
    env?: GatewayPreauthHandshakeEnv;
    envKeys?: GatewayPreauthHandshakeEnvKeys;
    preauthHandshakeTimeoutMs?: number;
};

export declare function resolveRunModel(row: RawUsageSession | null | undefined): string | undefined;

export type ResponseSpec = {
    shape?: string;
    note?: string;
};

export type RoutingMatrixSnapshot = GatewayRoutingMatrixSnapshot;

export type RpcBehaviorSpec = {
    blocking?: boolean;
    streamsEvents?: boolean;
    idempotent?: boolean;
    aborts?: string;
};

export declare const RUN_STREAM_EVENT_NAMES: {
    readonly MESSAGE_DELTA: "message.delta";
    readonly RUN_COMPLETED: "run.completed";
    readonly RUN_FAILED: "run.failed";
    readonly RUN_CANCELLED: "run.cancelled";
    readonly APPROVAL_REQUEST: "approval.request";
    readonly TOOL_CALL_STARTED: "tool.call.started";
    readonly TOOL_CALL_COMPLETED: "tool.call.completed";
    readonly TOOL_CALL_FAILED: "tool.call.failed";
};

export type RunEventStreamHandlers = {
    onEvent: (event: RunStreamEvent) => void;
    /** Transport / parse errors. Lifecycle "run.failed" is delivered via onEvent, not here. */
    onError?: (error: unknown) => void;
    /** Fired once after the stream has emitted its last event of the run. */
    onComplete?: () => void;
};

/**
 * Harness-agnostic source of live run events. Implementations bind to a
 * transport and translate native messages into the canonical RunStreamEvent
 * union; every emitted event's `event` field MUST be one of
 * RUN_STREAM_EVENT_NAMES.
 */
export interface RunEventStreamProvider {
    subscribe(params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
}

export type RunEventStreamSubscribeParams = {
    runId: string;
    /** Optional caller-supplied abort signal. Implementations MUST honor abort and dispose. */
    signal?: AbortSignal;
};

/** Disposes an active subscription. Idempotent. */
export type RunEventStreamSubscription = {
    dispose(): void | Promise<void>;
};

/**
 * Synthesizes tool events from {@link AgentRunPreviewItem}s by polling the
 * run-detail snapshot. Used as a stopgap until the Hermes SSE protocol emits
 * `tool.call.*` events natively.
 *
 * Default mode is one-shot: subscribe → fetch snapshot once → emit a
 * `tool.call.completed` event for each tool item → fire `onComplete` → dispose.
 *
 * For in-progress polling (multi-shot), pass `maxPolls > 1` and a
 * `pollIntervalMs`. The provider dedupes by `(toolName, at)` so the same tool
 * call is never emitted twice.
 *
 * This provider DOES NOT emit lifecycle events (`message.delta`,
 * `run.completed`, etc.). Compose it alongside a Hermes/gateway provider that
 * handles the lifecycle.
 */
export declare class RunPreviewPollProvider implements RunEventStreamProvider {
    private readonly fetchSnapshot;
    private readonly maxPolls;
    private readonly pollIntervalMs;
    constructor(options: RunPreviewPollProviderOptions);
    subscribe(params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
}

export type RunPreviewPollProviderOptions = {
    /** Caller-supplied fetcher for the run-detail snapshot (mobile uses gateway loaders; web hits HTTP directly). */
    fetchSnapshot: RunPreviewSnapshotFetcher;
    /**
     * Cap on how many snapshots to poll before giving up. Each poll synthesizes
     * tool events for items newer than the previous snapshot.
     *
     * Set to 1 for one-shot "stitch tool events after run completed" usage.
     * Set higher to track in-progress tool calls before backend SSE catches up.
     */
    maxPolls?: number;
    /** Delay between polls when {@link maxPolls} > 1. */
    pollIntervalMs?: number;
};

export type RunPreviewSnapshotFetcher = (runId: string, signal?: AbortSignal) => Promise<AgentRunDetailSnapshot | null>;

export type RunStreamApprovalChoice = "once" | "session" | "always" | "deny";

export type RunStreamApprovalRequestEvent = {
    event: typeof RUN_STREAM_EVENT_NAMES.APPROVAL_REQUEST;
    runId: string;
    choices: RunStreamApprovalChoice[];
    at?: number;
};

export type RunStreamEvent = RunStreamMessageDeltaEvent | RunStreamRunCompletedEvent | RunStreamRunFailedEvent | RunStreamRunCancelledEvent | RunStreamApprovalRequestEvent | RunStreamToolEvent;

export type RunStreamEventName = (typeof RUN_STREAM_EVENT_NAMES)[keyof typeof RUN_STREAM_EVENT_NAMES];

export type RunStreamMessageDeltaEvent = {
    event: typeof RUN_STREAM_EVENT_NAMES.MESSAGE_DELTA;
    runId: string;
    delta: string;
    at?: number;
};

export type RunStreamRunCancelledEvent = {
    event: typeof RUN_STREAM_EVENT_NAMES.RUN_CANCELLED;
    runId: string;
    reason?: string;
    at?: number;
};

export type RunStreamRunCompletedEvent = {
    event: typeof RUN_STREAM_EVENT_NAMES.RUN_COMPLETED;
    runId: string;
    output?: string;
    /** Provider-agnostic normalized usage, when the terminal stream carries it. */
    usage?: RuntimeUsage;
    at?: number;
    /** Present only on a dryRun short-circuit stream event (A3): "dry_run". */
    status?: RuntimeRunState;
};

export type RunStreamRunFailedEvent = {
    event: typeof RUN_STREAM_EVENT_NAMES.RUN_FAILED;
    runId: string;
    error: string;
    at?: number;
};

export type RunStreamToolCall = {
    id: string;
    name: string;
    status: RunStreamToolStatus;
    event?: string;
    input?: string;
    output?: string;
    error?: string;
    durationMs?: number;
    at?: number;
};

export type RunStreamToolEvent = {
    event: typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_STARTED | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_COMPLETED | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_FAILED;
    runId: string;
    toolCall: RunStreamToolCall;
    at?: number;
};

export type RunStreamToolStatus = "pending" | "running" | "completed" | "failed";

export type RuntimeClientOptions = Pick<HttpApiClientOptions, "baseUrl" | "fetchImpl" | "onTrace">;

/** @deprecated Import RuntimeProviderModule from core/runtime. */
export interface RuntimeProviderModule extends RuntimeProviderModuleBase {
}

export interface RuntimeProviderRegistry<M extends RuntimeProviderModule = RuntimeProviderModule> {
    resolveProvider(provider: string | null | undefined): M | null;
    listProviders(): readonly M[];
}

export declare function sameGatewayDaemon(leftBaseUrl: string | null | undefined, rightBaseUrl: string | null | undefined): boolean;

/** sessions.detail payload — kept loose because the gateway shape is still in flux. */
export type SessionDetailPayload = {
    key?: string;
    row?: unknown | null;
    usageSession?: unknown | null;
    preview?: unknown | null;
    errors?: {
        usage?: string | null;
    };
};

export type SessionDetailRequestParams = {
    key: string;
    previewLimit?: number;
    maxChars?: number;
};

export type SessionHttpRequestJson = <T>(path: string, init?: {
    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
    body?: unknown;
    timeoutMs?: number;
}) => Promise<T>;

export type SessionLoaders = {
    loadSessionsListRaw: (params: SessionsListRequestParams) => Promise<SessionsListPayloadWithCache>;
    loadSessionsUsageRaw: (params: Record<string, unknown>) => Promise<SessionsUsagePayload>;
    loadSessionsPreviewRaw: (params: SessionsPreviewRequestParams) => Promise<SessionsPreviewPayload>;
    loadSessionDetailRaw: (params: SessionDetailRequestParams) => Promise<SessionDetailPayload>;
    /**
     * Synchronous read of the sessions.list cache for the given param shape. Returns the cached
     * payload (or null) without triggering a fetch. Lets callers do a fast-path lookup before
     * deciding to issue a real `loadSessionsListRaw` call (e.g. detail-by-key fallback).
     */
    peekSessionsListCache: (params: SessionsListRequestParams) => SessionsListPayloadWithCache | null;
    /**
     * Mutate per-session settings via `sessions.patch`. Fire-and-forget — caller is expected to
     * invalidate any session detail / list / usage query on resolve. No client-side caching.
     */
    patchSession: (params: SessionPatchInput) => Promise<void>;
};

/**
 * sessions.patch params — operator-tunable session settings.
 *
 * `null` clears the value (back to inherit). `undefined` leaves the field untouched.
 * `fastMode` is a tri-state: `true` = on, `false` = off, `null` = inherit, `undefined` = unchanged.
 */
export type SessionPatchInput = {
    key: string;
    label?: string | null;
    thinkingLevel?: string | null;
    fastMode?: boolean | null;
    verboseLevel?: string | null;
    reasoningLevel?: string | null;
};

/** Align with loader `staleTime` (~10–15s) so SSE/stream invalidations coalesce without hammering the gateway. */
export declare const SESSIONS_DETAIL_CACHE_TTL_MS = 12000;

export type SessionsListPayload = {
    sessions?: RawSessionRow[];
    count?: number;
};

/** sessions.list "happy" payload — the gateway returns this when content actually changed. */
export type SessionsListPayloadWithCache = SessionsListPayload & {
    hash?: string;
    count?: number;
    ts?: number;
    path?: string;
};

/** Filters accepted by the gateway's `sessions.list` RPC. Mirrors the web's contract. */
export type SessionsListRequestParams = {
    includeGlobal?: boolean;
    includeUnknown?: boolean;
    includeDerivedTitles?: boolean;
    limit?: number;
    activeMinutes?: number;
    search?: string;
    label?: string;
    spawnedBy?: string;
    agentId?: string;
    lastHash?: string;
};

export type SessionsListRpcPayload = SessionsListPayloadWithCache | SessionsListUnchangedPayload;

/** sessions.list "no-op" payload — gateway sends `{ unchanged: true, hash }` when nothing moved. */
export type SessionsListUnchangedPayload = {
    unchanged: true;
    hash: string;
    count?: number;
    ts?: number;
    path?: string;
};

export type SessionsPreviewPayload = {
    previews?: Array<{
        key?: string;
        status?: string;
        items?: Array<{
            role?: string;
            text?: string;
            at?: number;
        }>;
    }>;
};

export type SessionsPreviewRequestParams = {
    keys: string[];
    limit?: number;
    maxChars?: number;
};

export type SessionsUsagePayload = {
    sessions?: RawUsageSession[];
    aggregates?: {
        byProvider?: Array<{
            provider?: string;
            totals?: {
                totalTokens?: number;
                totalCost?: number;
            };
        }>;
        byAgent?: Array<{
            agentId?: string;
            totals?: {
                totalCost?: number;
            };
            messages?: number;
        }>;
        messages?: {
            total?: number;
            toolCalls?: number;
            errors?: number;
        };
    };
    totals?: {
        totalCost?: number;
    };
};

export declare function setAgentConfigPathValue(config: Record<string, unknown>, path: string, value: AgentConfigFieldValue): Record<string, unknown>;

export declare function signPayload(privateKey: CryptoKey, payload: string): Promise<string>;

export declare function toIntInRange(raw: string | null, fallback: number, min: number, max: number): number;

export declare const tryResolveGatewayTargets: typeof tryResolveHttpWebSocketTargets;

export type TtlCacheEntry<TPayload> = {
    payload: TPayload | null;
    expiresAt: number;
    inFlight: Promise<TPayload> | null;
};

/**
 * Turns flat keys like `foo › bar` into `{ foo: { bar: value } }`.
 */
export declare function unflattenPortalConfigPatchKeys(flat: Record<string, unknown>, separator?: string): Record<string, unknown>;

export declare function utcDateYmd(date: Date): string;

export declare function waitForGatewayJob<TJob extends GatewayJobLike>(options: GatewayJobWaitOptions<TJob>): Promise<TJob>;

export declare function withFallback<TData>(params: {
    run: () => Promise<TData>;
    fallback: TData;
    area: string;
    expectedContract: string;
    note: string;
    /** Optional observability hook: fired when the envelope resolves live or mock (C2). */
    onResolve?: (info: FallbackResolveInfo) => void;
}): Promise<DataEnvelope<TData>>;

export declare function withMutationResult<TData>(params: {
    run: () => Promise<TData>;
    fallback: () => TData;
    area: string;
    expectedContract: string;
    note: string;
}): Promise<MutationResult<TData>>;