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

/** Throw a typed ProtocolMismatch error when the reported version is not `expected`. */
export declare function assertProtocolVersion(carrier: ProtocolVersionCarrier, expected: string): void;

export interface AuthStatusClient {
    listAuthStatus(): Promise<readonly RuntimeAuthStatus[]>;
}

/**
 * Build the canonical `dry_run` RuntimeRunStatus every provider's dryRun
 * short-circuit returns (A3). Single-source shape — same pattern as
 * normalizeRuntimeUsage: `dryRun: true` always builds + validates the
 * provider request first, then returns this WITHOUT any network call.
 */
export declare function buildDryRunStatus(model?: string): RuntimeRunStatus;

/** Build the single terminal stream event a dryRun streamRun() emits (A3). */
export declare function buildDryRunStreamEvent(model?: string): RunStreamRunCompletedEvent;

/** Grouping is presentation/ergonomics only; it partitions the taxonomy exactly. */
export declare const CAPABILITY_GROUPS: {
    readonly execution: readonly [
        "runs",
        "streaming",
        "batch"
    ];
    readonly lifecycle: readonly [
        "sessions",
        "tasks",
        "events"
    ];
    readonly introspection: readonly [
        "models",
        "usage",
        "authStatus"
    ];
    readonly domain: readonly [
        "kanban",
        "teams",
        "workspace",
        "operator",
        "discourse",
        "media",
        "wiki",
        "agentConfig"
    ];
};

/**
 * The unified capability taxonomy — the single, provider-agnostic list of
 * everything a provider may expose through the one client contract.
 *
 * It is the union of the two legacy axes: runtime SURFACES (`RUNTIME_SURFACES`)
 * and control-plane MODULES, de-duplicated (`workspace` appeared in both).
 * Every provider declares support for each key in ONE place; an unsupported
 * capability's call still exists on the client and throws a uniform, notated
 * `CapabilityUnavailable`.
 *
 * This module is purely additive: it introduces the taxonomy alongside the two
 * legacy axes it will replace. The `satisfies` bridges below are a compile-time
 * proof that the taxonomy is a strict superset of both — miss a surface or a
 * module and the build fails.
 */
export declare const CAPABILITY_TAXONOMY: readonly [
    "runs",
    "streaming",
    "batch",
    "sessions",
    "tasks",
    "events",
    "models",
    "usage",
    "authStatus",
    "kanban",
    "teams",
    "workspace",
    "operator",
    "discourse",
    "media",
    "wiki",
    "agentConfig"
];

export type CapabilityGroup = keyof typeof CAPABILITY_GROUPS;

export type CapabilityKey = (typeof CAPABILITY_TAXONOMY)[number];

/**
 * A provider's capability profile over the unified taxonomy. Every provider
 * publishes exactly one of these (Phase 2 makes it the single declaration
 * site); the client exposes the full surface and gates each call on it.
 */
export interface CapabilityMap {
    providerKind: string;
    supports: CapabilitySupport;
}

/** A provider's declared support for each capability. Absent key ⇒ unsupported. */
export type CapabilitySupport = Partial<Record<CapabilityKey, boolean>>;

export declare class CapabilityUnavailable extends Error {
    readonly providerId: string;
    readonly capability: string;
    readonly name = "CapabilityUnavailable";
    constructor(providerId: string, capability: string);
}

/** Compare a provider's reported protocol version against the expected one. */
export declare function checkProtocolVersion(carrier: ProtocolVersionCarrier, expected: string): ProtocolVersionCheck;

/**
 * Legacy axis #2 → unified. The control-plane modules
 * (`RuntimeControlPlaneDeclaration.modules`) collapse onto the same taxonomy;
 * `workspace` intentionally coincides with the runtime-surface mapping.
 */
export declare const CONTROL_PLANE_MODULE_CAPABILITY: {
    readonly sessions: "sessions";
    readonly models: "models";
    readonly usage: "usage";
    readonly tasks: "tasks";
    readonly workspace: "workspace";
    readonly authStatus: "authStatus";
    readonly events: "events";
};

export type ControlPlaneModule = keyof typeof CONTROL_PLANE_MODULE_CAPABILITY;

/**
 * Stateful translator from normalized control-plane events onto the canonical
 * run-stream union. Stateful in two ways: tool.completed frames omit the tool
 * name, so the translator remembers it from tool.started; and usage.updated
 * frames carry usage on their own, so the last-seen usage is remembered and
 * attached to the terminal RUN_COMPLETED event (matching the Gemini provider's
 * precedent of surfacing accumulated usage on the terminal event). Events with
 * no run-visible projection (reasoning deltas, usage ticks, stream
 * housekeeping) map to null.
 */
export declare function createControlPlaneRunStreamTranslator(): (event: RuntimeControlPlaneEvent) => RunStreamEvent | null;

export declare function createProviderRegistry<M extends RuntimeProviderModule>(options?: CreateRuntimeProviderRegistryOptions<M>): RuntimeProviderRegistry<M>;

/**
 * Adapt a control-plane event client (subscribe-by-operationId) into the
 * run-event stream contract (subscribe-by-runId) — the WS half of the gateway
 * streamRun bridge, but provider-agnostic: any RuntimeEventClient fits.
 *
 * `RuntimeEventClient` has no onComplete slot of its own, so it is synthesized
 * here: once a translated terminal event (run.completed / run.failed /
 * run.cancelled) is forwarded, `handlers.onComplete` fires exactly once and
 * any further control-plane frames for this subscription are ignored — every
 * other RunEventStreamProvider in this package honors that contract (see
 * core/gateway/run/sse-run-event-provider.ts and event-stream.ts) and
 * consumers (e.g. hermes/chat-run.ts) rely on it to resolve.
 *
 * A control-plane event client reports errors PER FRAME (a malformed frame
 * leaves the subscription alive), so errors forwarded here are tagged
 * NON-terminal via {@link markNonTerminalStreamError}: the gateway bridge
 * surfaces them to `onError` for observability without settling the run. True
 * stream termination comes from a terminal run event, connection loss (raised
 * by the provider wrapper), or the caller's AbortSignal — never a single bad
 * frame.
 */
export declare function createRunEventStreamFromControlPlane(events: RuntimeEventClient): RunEventStreamProvider;

export declare function createRuntimeClient(provider: string, options: CreateRuntimeClientOptions): RuntimeClient;

export type CreateRuntimeClientOptions = {
    registry: RuntimeProviderRegistry;
    clientOptions: RuntimeClientOptions;
};

export declare function createRuntimeControlClient(provider: string, options?: RuntimeControlClientOptions): Promise<RuntimeControlClient>;

export declare function createRuntimeControlExtensionRegistry(entries?: Iterable<RuntimeControlExtensionEntry>): RuntimeControlExtensionRegistry;

export declare function createRuntimeProviderRegistry(options?: CreateRuntimeProviderRegistryOptions): RuntimeProviderRegistry;

export type CreateRuntimeProviderRegistryOptions<M extends RuntimeProviderModule = RuntimeProviderModule> = {
    modules?: readonly M[] | null;
    allowOverrides?: boolean;
};

export declare function createUnavailableRuntimeControlClient(providerId: string, capabilities: ReadonlySet<string>): RuntimeControlClient;

export declare function defineRuntimeControlExtension<T>(id: string): RuntimeControlExtensionDescriptor<T>;

/**
 * Estimate run cost from normalized usage + consumer-supplied prices. The
 * package ships NO price table — prices are always the caller's. Any missing
 * token count or price contributes 0.
 */
export declare function estimateUsageCost(usage: RuntimeUsage, prices: TokenPrices): number;

export declare const GATEWAY_RAW_EXTENSION: RuntimeControlExtensionDescriptor<RawGatewayChannel>;

export declare function getBrowserWindowOrigin(): string | null;

export declare function inspectRuntimeEventSequence(events: readonly RuntimeControlPlaneEvent[]): RuntimeEventSequenceInspection;

/** Narrow an arbitrary string to a `CapabilityKey`. */
export declare function isCapabilityKey(value: string): value is CapabilityKey;

/** True when an error was tagged by {@link markNonTerminalStreamError}. */
export declare function isNonTerminalStreamError(error: unknown): boolean;

export declare function isRuntimeRunStartBody(value: unknown): value is RuntimeRunStartBody;

export type ListSessionsOptions = SessionRequestOptions & {
    cursor?: string;
    limit?: number;
};

/**
 * Tag an error as a NON-terminal stream error: the gateway bridge forwards it
 * to `handlers.onError` (observability) but does not settle/reject the stream.
 * Used at the control-plane→run-stream seam where a single bad frame must not
 * kill an otherwise-live subscription. Mutates and returns the same error
 * (non-enumerable marker) so the forwarded value is unchanged for consumers.
 * Non-object errors can't carry the marker and are treated as terminal.
 */
export declare function markNonTerminalStreamError<E>(error: E): E;

export interface ModelCatalogClient {
    listModels(query?: {
        cursor?: string;
        limit?: number;
    }): Promise<RuntimePage<RuntimeModelDescriptor>>;
}

export declare function normalizeRuntimeBasePath(rawBasePath: string | null | undefined): string;

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

/**
 * Normalize a flat provider-native usage record into RuntimeUsage. Tolerant of
 * snake_case / camelCase across providers. Provider mappers are preferred where
 * the native (possibly nested) object is in hand; this covers callers holding
 * only the legacy flat `RuntimeRunStatus.usage`. `providerKind` is reserved for
 * future provider-specific disambiguation.
 */
export declare function normalizeRuntimeUsage(raw: Record<string, number> | undefined, providerKind: string): RuntimeUsage | undefined;

export type ProtocolVersionCarrier = {
    protocolVersion?: string | null;
};

export type ProtocolVersionCheck = {
    ok: boolean;
    expected: string;
    actual: string | null;
};

export interface RawGatewayChannel {
    request<TResult = unknown>(operationId: string, payload?: Readonly<Record<string, unknown>>, options?: RawGatewayRequestOptions): Promise<TResult>;
    subscribe(listener: (event: RawGatewayEvent) => void): () => void;
    getConnectionState(): RawGatewayConnectionState;
    onConnectionState(listener: (state: RawGatewayConnectionState) => void): () => void;
    connect(): Promise<void>;
    dispose(): Promise<void>;
}

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

export type RawGatewayEvent = Readonly<{
    event: string;
    payload: unknown;
}>;

export type RawGatewayRequestOptions = Readonly<{
    signal?: AbortSignal;
}>;

export declare function resolvePublicRuntimeAsset(pathname: string, rawBasePath: string | null | undefined): 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.
     *
     * TERMINALITY: by default an `onError` is TERMINAL — it ends the stream and
     * (through the gateway bridge) rejects/settles the run. A provider that
     * surfaces a *per-frame*, NON-terminal error (e.g. a single malformed frame
     * on a still-live subscription) MUST mark it with
     * {@link markNonTerminalStreamError} so the bridge forwards it for
     * observability without tearing the stream down. Connection loss is terminal
     * and stays unmarked.
     */
    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>;
};

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 declare const RUNTIME_CONTROL_PLANE_EVENT_NAMES: readonly [
    "operation.started",
    "operation.updated",
    "message.delta",
    "reasoning.delta",
    "tool.started",
    "tool.progress",
    "tool.completed",
    "approval.requested",
    "approval.resolved",
    "usage.updated",
    "stream.reconnected",
    "stream.gap",
    "operation.completed",
    "operation.failed",
    "operation.cancelled",
    "operation.interrupted"
];

/**
 * Legacy axis #1 → unified. `satisfies Record<RuntimeSurface, …>` forces every
 * runtime surface to map onto a real capability; the build breaks if a surface
 * is added upstream without a home here.
 */
export declare const RUNTIME_SURFACE_CAPABILITY: {
    readonly runs: "runs";
    readonly streaming: "streaming";
    readonly batch: "batch";
    readonly media: "media";
    readonly wiki: "wiki";
    readonly agentConfig: "agentConfig";
    readonly teams: "teams";
    readonly kanban: "kanban";
    readonly workspace: "workspace";
    readonly operator: "operator";
    readonly discourse: "discourse";
};

/** Every surface a provider may declare support for. */
export declare const RUNTIME_SURFACES: readonly [
    "runs",
    "streaming",
    "media",
    "wiki",
    "agentConfig",
    "teams",
    "kanban",
    "workspace",
    "operator",
    "discourse",
    "batch"
];

export declare const RUNTIME_TRANSPORT_KINDS: readonly [
    "http",
    "sse",
    "websocket",
    "json-rpc",
    "stdio",
    "unix-socket"
];

export interface RuntimeAuthStatus {
    providerId: string;
    profileId?: string;
    status: "authenticated" | "unauthenticated" | "expired" | "unknown";
    expiresAt?: string;
    sourceCategory?: string;
    reasonCode?: string;
    metadata: RuntimeControlPlaneMetadata;
}

export type RuntimeBatchCounts = {
    total?: number;
    processing?: number;
    succeeded?: number;
    errored?: number;
    canceled?: number;
    expired?: number;
};

export type RuntimeBatchOutcome = "succeeded" | "errored" | "canceled" | "expired" | (string & {});

/** One entry in a batch submission — a run body plus a caller correlation id. */
export type RuntimeBatchRequest = {
    /** Caller-chosen id, echoed on the matching result. */
    customId: string;
    body: RuntimeRunStartBody;
};

export type RuntimeBatchResult = {
    customId: string;
    outcome: RuntimeBatchOutcome;
    /** Present when outcome === "succeeded": the normalized run status (incl. tokens). */
    run?: RuntimeRunStatus;
    error?: string;
};

export type RuntimeBatchState = "in_progress" | "canceling" | "completed" | "cancelled" | "failed" | (string & {});

export type RuntimeBatchStatus = {
    batch_id: string;
    status: RuntimeBatchState;
    counts?: RuntimeBatchCounts;
    createdAt?: number | string;
    endedAt?: number | string;
    /** True once results are retrievable (the provider batch has ended). */
    resultsAvailable?: boolean;
};

/** Provider-declared capability profile. Returned by RuntimeClient. */
export type RuntimeCapabilities = {
    providerKind: string;
    protocolVersion?: string | null;
    auth?: {
        type?: string;
        required?: boolean;
    };
    supports: Partial<Record<RuntimeSurface, boolean>>;
};

/**
 * The UNIVERSAL agent-runtime contract every provider implements.
 * Gateway backends implement this via `GatewayApiClient` (teams/kanban/
 * workspace/operator live there). React’s `GatewayClient*` names are the
 * WebSocket RPC context only — there is no exported `GatewayClient` interface.
 */
export interface RuntimeClient {
    getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
    startRun(body: RuntimeRunStartBody): Promise<RuntimeRunStatus>;
    /**
     * Optional run lifecycle. Three real behaviors exist in this package:
     *
     * - **omit** — method absent; consumers null-check (`client.getRun?.(id)`).
     * - **server** — real backend retrieval/cancel (Codex background responses,
     *   Claude Managed Agents sessions, `GatewayApiClient` HTTP runs).
     * - **sync-store** — synchronous providers (Claude Messages, Gemini) keep a
     *   local `SynchronousRunStore` of terminal statuses from `startRun`;
     *   `getRun` returns the remembered status or an honest `unknown` status for
     *   foreign ids and **does not throw**. `cancelRun` is a no-op success on
     *   an already-terminal run.
     *
     * Providers that expose the method but cannot serve it any other way should
     * throw `ApiClientError(EndpointNotFound)` (`unsupported-throw` semantics).
     */
    getRun?(runId: string): Promise<RuntimeRunStatus>;
    cancelRun?(runId: string): Promise<{
        status: string;
    }>;
    /**
     * Start a run and stream it as canonical RunStreamEvents. Optional.
     *
     * **Streaming duality (intentional):** runtime-only providers implement
     * `streamRun(body, handlers)`. Gateway providers typically omit this and
     * expose subscribe-by-`runId` via `createSseRunEventProvider` /
     * `RunEventStreamProvider` on the gateway provider module instead.
     */
    streamRun?(body: RuntimeRunStartBody, handlers: RunEventStreamHandlers, options?: {
        signal?: AbortSignal;
    }): Promise<void>;
    /**
     * Batch surface (optional). Providers that support async batch processing
     * declare `supports.batch` and implement these; others omit them. Consumers
     * null-check (`client.submitBatch?.(…)`) or gate on `RuntimeCapabilities`.
     */
    submitBatch?(requests: RuntimeBatchRequest[]): Promise<RuntimeBatchStatus>;
    getBatch?(batchId: string): Promise<RuntimeBatchStatus>;
    cancelBatch?(batchId: string): Promise<RuntimeBatchStatus>;
    /**
     * Retrieve batch results. Throws an `EndpointNotFound`-class error if the
     * batch has not ended yet — poll `getBatch` until `resultsAvailable` is true.
     */
    getBatchResults?(batchId: string): Promise<RuntimeBatchResult[]>;
}

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

export interface RuntimeControlClient {
    readonly authStatus: AuthStatusClient;
    readonly sessions: SessionClient;
    readonly models: ModelCatalogClient;
    readonly usage: UsageClient;
    readonly tasks: TaskClient;
    readonly workspace: WorkspaceClient;
    readonly events: RuntimeEventClient;
    readonly extensions: RuntimeControlExtensionRegistry;
    dispose(): Promise<void>;
}

export type RuntimeControlClientFactory = (options: RuntimeControlClientOptions) => Promise<RuntimeControlClient>;

export type RuntimeControlClientOptions = {
    baseUrl?: string;
    webSocketUrl?: string;
    token?: string;
    resolveAuth?: TransportAuthResolver;
    signal?: AbortSignal;
    trace?: (event: TransportLifecycleEvent) => void;
    /** Provider-neutral gateway handshake and request settings for an owned connection. */
    gatewayConnection?: GatewayRpcClientOptions;
    /** Opt-in bounded retry policy for reconnecting an owned gateway after a retryable drop. */
    gatewayReconnect?: TransportRetryPolicy;
    transport?: GatewayTransport;
    registry?: RuntimeProviderRegistry;
};

export type RuntimeControlExtensionDescriptor<T> = Readonly<{
    id: string;
    [extensionType]?: T;
}>;

export interface RuntimeControlExtensionRegistry {
    has<T>(descriptor: RuntimeControlExtensionDescriptor<T>): boolean;
    get<T>(descriptor: RuntimeControlExtensionDescriptor<T>): T | undefined;
    list(): readonly string[];
}

export type RuntimeControlPlaneDeclaration = {
    transports?: RuntimeTransportCapabilities;
    modules?: Partial<Record<"sessions" | "models" | "usage" | "tasks" | "workspace" | "authStatus" | "events", true>>;
};

export type RuntimeControlPlaneEvent = (RuntimeControlPlaneEventBase & {
    event: "operation.started";
}) | (RuntimeControlPlaneEventBase & {
    event: "operation.updated";
    update: unknown;
}) | (RuntimeControlPlaneEventBase & {
    event: "message.delta";
    delta: string;
}) | (RuntimeControlPlaneEventBase & {
    event: "reasoning.delta";
    delta: string;
}) | (RuntimeControlPlaneEventBase & {
    event: "tool.started";
    toolCallId: string;
    toolName: string;
}) | (RuntimeControlPlaneEventBase & {
    event: "tool.progress";
    toolCallId: string;
    progress: unknown;
}) | (RuntimeControlPlaneEventBase & {
    event: "tool.completed";
    toolCallId: string;
    result?: unknown;
}) | (RuntimeControlPlaneEventBase & {
    event: "approval.requested";
    approvalId: string;
    request?: unknown;
}) | (RuntimeControlPlaneEventBase & {
    event: "approval.resolved";
    approvalId: string;
    approved: boolean;
}) | (RuntimeControlPlaneEventBase & {
    event: "usage.updated";
    usage: RuntimeUsage;
}) | (RuntimeControlPlaneEventBase & {
    event: "stream.reconnected";
    cursor?: string;
}) | (RuntimeControlPlaneEventBase & {
    event: "stream.gap";
    reason: string;
}) | (RuntimeControlPlaneEventBase & {
    event: "operation.completed";
}) | (RuntimeControlPlaneEventBase & {
    event: "operation.failed";
    error: unknown;
}) | (RuntimeControlPlaneEventBase & {
    event: "operation.cancelled";
}) | (RuntimeControlPlaneEventBase & {
    event: "operation.interrupted";
    reason?: string;
});

export type RuntimeControlPlaneEventName = (typeof RUNTIME_CONTROL_PLANE_EVENT_NAMES)[number];

export type RuntimeControlPlaneMetadata = {
    provider: string;
    stability: RuntimeProviderStability;
    source: RuntimeControlPlaneSource;
    providerData?: unknown;
};

export type RuntimeControlPlaneSource = {
    transport: "http" | "sse" | "websocket" | "json-rpc" | "stdio" | "unix-socket";
    method: string;
};

export interface RuntimeEventClient {
    subscribe(params: {
        operationId: string;
        cursor?: string;
        signal?: AbortSignal;
    }, handlers: {
        onEvent(event: RuntimeControlPlaneEvent): void;
        onError?(error: unknown): void;
    }): Promise<RuntimeEventSubscription>;
}

export interface RuntimeEventSequenceInspection {
    valid: boolean;
    terminalCount: number;
    gaps: number;
}

export interface RuntimeEventSubscription {
    dispose(): void | Promise<void>;
}

export interface RuntimeModelDescriptor {
    providerId: string;
    id: string;
    displayName?: string;
    availability: "available" | "unavailable" | "unknown";
    capabilities?: Readonly<Record<string, boolean>>;
    authenticated?: boolean;
    metadata: RuntimeControlPlaneMetadata;
}

export type RuntimePage<T> = {
    data: readonly T[];
    nextCursor?: string;
};

export interface RuntimeProviderModule {
    kind: string;
    aliases?: readonly string[];
    capabilities?: Partial<Record<RuntimeSurface, boolean>>;
    controlPlane?: RuntimeControlPlaneDeclaration;
    createClient?: (clientOptions: RuntimeClientOptions) => RuntimeClient;
    createRuntimeControlClient?: RuntimeControlClientFactory;
    /** @deprecated Use createClient for new provider modules. */
    createApiClient?: (clientOptions: RuntimeClientOptions) => RuntimeClient;
}

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

export type RuntimeProviderStability = "stable" | "experimental";

export type RuntimeRunInput = string | RuntimeRunMessage[];

/** A single conversation message. Structurally shared by every provider. */
export type RuntimeRunMessage = {
    role: string;
    content: string | Record<string, unknown>[];
    [key: string]: unknown;
};

/**
 * The UNIVERSAL run-start body. Carries only fields every agent runtime
 * understands. Provider/gateway-only concepts (sessions, routing, target
 * profiles, tasks) are NOT here — they live on `GatewayRunStartBody`.
 */
export type RuntimeRunStartBody = {
    input: RuntimeRunInput;
    /** System / developer instructions (Anthropic `system`). */
    instructions?: string;
    model?: string;
    tools?: Record<string, unknown>[];
    metadata?: Record<string, unknown>;
    dryRun?: boolean;
};

export type RuntimeRunState = "started" | "running" | "completed" | "failed" | "cancelled" | "stopping" | "dry_run" | (string & {});

/** The UNIVERSAL run status. Gateway-only fields live on `GatewayRunStatus`. */
export type RuntimeRunStatus = {
    run_id: string;
    status: RuntimeRunState;
    model?: string;
    output?: string;
    response?: string;
    error?: string;
    /**
     * @deprecated Raw provider-native token counts. Use `tokens` for portable,
     * normalized usage. Still populated for backward compatibility.
     */
    usage?: Record<string, number>;
    /** Provider-agnostic normalized token usage. */
    tokens?: RuntimeUsage;
};

export type RuntimeSessionState = "pending" | "active" | "completed" | "cancelled" | "failed" | "unknown";

export interface RuntimeSessionSummary {
    id: string;
    providerId: string;
    title?: string;
    state: RuntimeSessionState;
    createdAt?: string;
    updatedAt?: string;
    providerKind: string;
    model?: string;
    workspaceId?: string;
    metadata: RuntimeControlPlaneMetadata;
}

export declare function runtimeSupports(capabilities: RuntimeCapabilities, surface: RuntimeSurface): boolean;

export type RuntimeSurface = (typeof RUNTIME_SURFACES)[number];

export type RuntimeTaskState = "pending" | "running" | "completed" | "cancelled" | "failed" | "unknown";

export interface RuntimeTaskSummary {
    id: string;
    state: RuntimeTaskState;
    createdAt?: string;
    updatedAt?: string;
    runId?: string;
    sessionId?: string;
    threadId?: string;
    cancellable?: boolean;
    metadata: RuntimeControlPlaneMetadata;
}

export type RuntimeTransportCapabilities = Partial<Record<RuntimeTransportKind, RuntimeTransportCapability>>;

export type RuntimeTransportCapability = {
    kind: RuntimeTransportKind;
    stability: RuntimeProviderStability;
    authenticated: boolean;
    reconnect?: boolean;
    replay?: boolean;
    cancellation?: boolean;
};

export type RuntimeTransportKind = (typeof RUNTIME_TRANSPORT_KINDS)[number];

export declare function runtimeTransportSupports(capabilities: RuntimeTransportCapabilities, kind: RuntimeTransportKind): boolean;

/** Canonical, provider-agnostic token usage for a single run. */
export type RuntimeUsage = {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    /** Tokens served from prompt cache. */
    cacheReadTokens?: number;
    /** Tokens written to prompt cache (Anthropic "cache_creation"). */
    cacheWriteTokens?: number;
    /** Lossless provider-native numeric fields, flattened. */
    raw?: Record<string, number>;
};

export interface RuntimeUsageCost {
    availability: "available" | "estimated" | "unavailable";
    amount?: number;
    currency?: string;
    calculationSource?: string;
}

export interface RuntimeUsageQuery {
    startTime?: string;
    endTime?: string;
    providerId?: string;
    model?: string;
    sessionId?: string;
    agentId?: string;
}

export interface RuntimeUsageSummary {
    tokens: RuntimeUsage;
    cost: RuntimeUsageCost;
    aggregation?: string;
    metadata: RuntimeControlPlaneMetadata;
}

export interface RuntimeWorkspaceDescriptor {
    id: string;
    providerId: string;
    displayName?: string;
    root?: string;
    accessMode: "read-only" | "read-write" | "unknown";
    metadata: RuntimeControlPlaneMetadata;
}

export interface SessionClient {
    listSessions(query?: ListSessionsOptions): Promise<RuntimePage<RuntimeSessionSummary>>;
    getSession(id: string, options?: SessionRequestOptions): Promise<RuntimeSessionSummary>;
    cancelSession?(id: string, options?: SessionRequestOptions): Promise<RuntimeSessionSummary>;
}

export type SessionRequestOptions = {
    signal?: AbortSignal;
};

/** True iff `map` declares `key` supported. The only place `=== true` lives. */
export declare function supportsCapability(map: CapabilityMap, key: CapabilityKey): boolean;

export interface TaskClient {
    listTasks(query?: {
        cursor?: string;
        limit?: number;
    }): Promise<RuntimePage<RuntimeTaskSummary>>;
    getTask(id: string): Promise<RuntimeTaskSummary>;
    cancelTask?(id: string): Promise<RuntimeTaskSummary>;
}

/** Per-million-token prices supplied by the consumer. No defaults ship. */
export type TokenPrices = {
    inputPerMTok?: number;
    outputPerMTok?: number;
    cacheReadPerMTok?: number;
    cacheWritePerMTok?: number;
};

/** Throw a typed EndpointNotFound for a surface this provider does not serve. */
export declare function unsupportedRuntimeSurface(providerKind: string, surface: RuntimeSurface): never;

export interface UsageClient {
    getUsage(query?: RuntimeUsageQuery): Promise<RuntimeUsageSummary>;
}

export declare function withRuntimeBasePath(pathname: string, rawBasePath: string | null | undefined): string;

export declare function withRuntimeControlExtensions(client: RuntimeControlClient, entries: Iterable<RuntimeControlExtensionEntry>): RuntimeControlClient;

export interface WorkspaceClient {
    listWorkspaces(): Promise<readonly RuntimeWorkspaceDescriptor[]>;
    getWorkspace(id: string): Promise<RuntimeWorkspaceDescriptor>;
}