@cavi-ai/api-client

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 declare class ApiClientError extends Error {
    readonly type: ApiClientErrorType | string;
    readonly code: ApiClientErrorCode | string;
    readonly runtime?: RuntimeErrorMetadata;
    constructor(message: string, options?: ApiClientErrorOptions);
}

export declare enum ApiClientErrorCode {
    Unknown = "unknown",
    ValidationFailed = "validation_failed",
    InvalidConfig = "invalid_config",
    InvalidJson = "invalid_json",
    HttpRequestFailed = "http_request_failed",
    GatewayError = "gateway_error",
    RequestFailed = "request_failed",
    Timeout = "timeout",
    Aborted = "aborted",
    SocketError = "socket_error",
    SocketClosed = "socket_closed",
    SocketUnavailable = "socket_unavailable",
    ConnectFailed = "connect_failed",
    BackendUnavailable = "backend_unavailable",
    EndpointNotFound = "endpoint_not_found",
    ProtocolMismatch = "protocol_mismatch",
    AuthRequired = "auth_required",
    AuthForbidden = "auth_forbidden",
    CapabilityUnavailable = "capability_unavailable",
    PermissionDenied = "permission_denied",
    InvalidRequest = "invalid_request",
    Conflict = "conflict",
    RateLimited = "rate_limited",
    TransportUnavailable = "transport_unavailable",
    TransportProtocolError = "transport_protocol_error",
    ServerOverloaded = "server_overloaded"
}

export type ApiClientErrorOptions = {
    type?: ApiClientErrorType | string;
    code?: ApiClientErrorCode | string;
    cause?: unknown;
    runtime?: RuntimeErrorMetadata;
};

export declare enum ApiClientErrorType {
    Unknown = "unknown",
    Validation = "validation",
    Configuration = "configuration",
    Http = "http",
    GatewayHttp = "gateway_http",
    GatewayRpc = "gateway_rpc",
    Transport = "transport",
    Timeout = "timeout",
    Abort = "abort",
    BackendUnavailable = "backend_unavailable",
    Auth = "auth"
}

export type ApiKeyCredentialOptions = {
    /** Header name for the key. Defaults to "Authorization". */
    header?: string;
    /** Extra static headers (e.g. { "anthropic-version": "2023-06-01" }). */
    extra?: Record<string, string>;
};

/** API-key scheme (e.g. Anthropic: header "x-api-key" + "anthropic-version"). */
export declare function apiKeyCredentials(key: string, options?: ApiKeyCredentialOptions): CredentialResolver;

export declare function appendHttpQuery(path: string, query?: Record<string, string | number | boolean | undefined>): string;

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

/**
 * Validate and normalize a caller-supplied **relative** path, returning the
 * cleaned `a/b/c` form or throwing on anything unsafe.
 *
 * This is the **opt-in** companion to the manifest workspace whitelist
 * (`resolveTeamWorkspacePath`). The whitelist is the primary, recommended guard:
 * a path the consumer never declared can never be resolved. Reach for this only
 * when a downstream surface must accept a *free-form* relative path — e.g. a raw
 * `?path=` value a consumer wants to hand to a workspace/wiki file endpoint
 * (`GATEWAY_WIKI_API_ENDPOINTS.read`, a manifest action `query`).
 *
 * `appendHttpQuery` does **not** sanitize values — it only URL-encodes them, so
 * `?path=../secret` becomes `?path=..%2Fsecret` and the backend decodes it back.
 * Run untrusted path values through this first, then pass the result as a query
 * value via `appendHttpQuery` (which encodes it).
 *
 * Rejects: empty/whitespace, absolute (`/…`), protocol-relative (`//…`), URL
 * schemes (`file:`, `http:`…), backslashes, and any `.`/`..` segment — including
 * percent-encoded forms such as `%2e%2e`. Interior `./` and duplicate slashes
 * are collapsed. The return value is **not** URL-encoded.
 *
 * This intentionally mirrors the relative-path rules the team manifest enforces
 * internally for workspace whitelist entries (`src/contracts/team-manifest.ts`).
 * Both are guarded by `safe-relative-path.test.ts`; keep them in lockstep.
 */
export declare function assertSafeRelativePath(value: string): string;

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

/** Standard bearer scheme. Emits nothing when the token is empty. */
export declare function bearerCredentials(token: string | null | undefined): CredentialResolver;

/**
 * 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;

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

export interface CachedTeamManifestSource extends TeamManifestSource {
    /** Re-run the loader and replace the cached manifest. */
    refresh(): Promise<TeamManifest>;
}

/** 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"
];

/**
 * Thrown by internal plumbing (e.g. the gateway streamRun bridges) for a
 * caller mistake the transport can name before any request is made. The
 * facade classifies it into a `request-invalid` gap — consumers never see it.
 */
export declare class CapabilityCallRejected extends Error {
    readonly httpStatus?: number | undefined;
    readonly name = "CapabilityCallRejected";
    constructor(message: string, httpStatus?: number | undefined);
}

/**
 * The single client surface (the redesign's core invariant): every capability
 * accessor exists on every provider. Gated surfaces never throw and never go
 * missing — an unsupported or failed call resolves `ok: false` with a
 * structured `ContractGap` (the same notation the throwing gate once carried),
 * while a supported call resolves `ok: true` with a live result. The only
 * throws left on a gated call are the envelope contract's carve-outs: auth
 * errors (401/403) and unknown-classified errors. Feature-detect via
 * `getCapabilityMap()`, or just call and branch on `result.ok`. Support is
 * decided by the runtime-resolved capabilities merged over the static fallback
 * (design decision M1).
 */
export interface CapabilityClient {
    readonly providerKind: string;
    /** Merged (runtime over static) capability profile. */
    getCapabilityMap(): Promise<CapabilityMap>;
    /** Runtime-resolved manifest, when the provider publishes one. */
    getManifest(): Promise<TeamManifest | null>;
    /** Drop the memoized runtime resolution and resolve again. */
    refreshCapabilities(): Promise<CapabilityMap>;
    /**
     * Tear down the client: dispose the control plane and run provider teardown.
     * In-flight gateway `streamRun` bridges are settled as part of teardown
     * (their in-flight calls are aborted, so pending `streamRun` promises resolve
     * rather than hang), then any transport (SSE/WebSocket) is closed.
     */
    dispose(): Promise<void>;
    startRun(body: RuntimeRunStartBody): Promise<CapabilityResult<RuntimeRunStatus>>;
    getRun(runId: string): Promise<CapabilityResult<RuntimeRunStatus>>;
    cancelRun(runId: string): Promise<CapabilityResult<{
        status: string;
    }>>;
    /**
     * Stream a run, unified across providers. The resolved `ok` reflects the
     * STREAMING CALL, not the run: a clean stream (or one whose run merely failed
     * as an event) resolves `ok: true` with a {@link RunStreamOutcome} carrying
     * the captured `runId` and the terminal `outcome` seen. A stream that a
     * transport error tore down resolves `ok: false` with a classified gap. A
     * caller-initiated abort (via `options.signal`), or a provider-internal
     * AbortError, resolves `ok: false` with a `request-aborted` gap — never a
     * silent `ok: true` — and, when a `runId` is known and the runtime exposes
     * `cancelRun`, issues a best-effort `cancelRun(runId)` so no gateway run is
     * orphaned (the gap note records whether a cancel was requested). Auth
     * (401/403) and unknown-classified errors still throw.
     */
    streamRun(body: StreamRunBody, handlers: RunEventStreamHandlers, options?: {
        signal?: AbortSignal;
    }): Promise<CapabilityResult<RunStreamOutcome>>;
    submitBatch(requests: RuntimeBatchRequest[]): Promise<CapabilityResult<RuntimeBatchStatus>>;
    getBatch(batchId: string): Promise<CapabilityResult<RuntimeBatchStatus>>;
    cancelBatch(batchId: string): Promise<CapabilityResult<RuntimeBatchStatus>>;
    getBatchResults(batchId: string): Promise<CapabilityResult<RuntimeBatchResult[]>>;
    readonly sessions: CapabilityGated<SessionClient>;
    readonly tasks: CapabilityGated<TaskClient>;
    readonly events: CapabilityGated<RuntimeEventClient>;
    readonly models: CapabilityGated<ModelCatalogClient>;
    readonly usage: CapabilityGated<UsageClient>;
    readonly authStatus: CapabilityGated<AuthStatusClient>;
    readonly workspace: CapabilityGated<WorkspaceClient>;
    readonly kanban: CapabilityGated<KanbanClient>;
    readonly teams: CapabilityGated<TeamDirectory>;
    readonly media: CapabilityGated<GatewayMediaClient>;
    readonly wiki: CapabilityGated<GatewayWikiClient>;
    readonly agentConfig: CapabilityGated<GatewayAgentConfigClient>;
}

export type CapabilityClientBackends = {
    /** Control-plane backing for sessions/tasks/events/models/usage/authStatus/workspace. */
    controlPlane?: LazyAsync<RuntimeControlClient>;
    kanban?: LazyAsync<KanbanClient>;
    media?: LazyAsync<GatewayMediaClient>;
    wiki?: LazyAsync<GatewayWikiClient>;
    agentConfig?: LazyAsync<GatewayAgentConfigClient>;
    /** Supply the directory or a sync factory. */
    teams?: TeamDirectory | (() => TeamDirectory);
};

export type CapabilityGated<T> = {
    readonly [K in keyof T]-?: CapabilityGatedMethod<NonNullable<T[K]>>;
};

/** A backend surface re-typed to the non-throwing facade contract. */
export type CapabilityGatedMethod<F> = F extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<CapabilityResult<R>> : F extends (...args: infer A) => infer R ? (...args: A) => Promise<CapabilityResult<R>> : F extends object ? CapabilityGated<F> : never;

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;
}

/**
 * The non-throwing capability contract (design decision 2026-07-21): every
 * facade method resolves one of these. `ok: false` states honestly that
 * nothing happened and why — there is no mock data and no fabricated success.
 * The only throws left on the facade are auth errors (401/403) and
 * unknown-classified errors, the same carve-outs as `withFallback`.
 */
export type CapabilityResult<T> = {
    ok: true;
    data: T;
    source: "live";
} | {
    ok: false;
    data: null;
    gap: ContractGap;
};

/** 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;

/**
 * Classify a failed capability call into a gap, preserving the envelope
 * contract's carve-outs: auth errors and unknown-classified errors rethrow.
 * HTTP 4xx caller errors (except 401/403/404) become `request-invalid`.
 *
 * 404 and 5xx are classified explicitly here rather than left to
 * `classifyFallbackError`: that classifier only recognizes `GatewayHttpError`
 * instances via `instanceof`, so a bare `{ status }` error (as thrown by
 * non-gateway transports) would otherwise fall through as `unknown`.
 * This deliberately diverges from `classifyFallbackError` for the 4xx band
 * (e.g. it reports `GatewayHttpError` 429 as `request-invalid`, not
 * `backend-unavailable`) because 4xx other than 401/403/404 is a caller
 * error, not backend degradation.
 */
export declare function classifyCapabilityFailure(params: {
    error: unknown;
    area: string;
    expectedContract: string;
    call: string;
}): ContractGap;

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

/**
 * 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" | "capability-unsupported" | "request-invalid" | "request-aborted" | "unknown";

export declare function createApiClient(provider: string, options?: CreateApiClientOptions): CapabilityClient;

export type CreateApiClientOptions = {
    /** Provider registry; defaults to the built-in gateway modules. */
    registry?: RuntimeProviderRegistry;
    baseUrl?: string;
    /** Gateway WebSocket URL; derived from `baseUrl` when omitted. */
    webSocketUrl?: string;
    token?: string;
    fetchImpl?: typeof fetch;
    /** Advertised WS client id for gateways that validate it. */
    clientId?: string;
    /**
     * `Origin` header for the gateway WebSocket handshake. Origin-gated gateways
     * reject connections whose origin is absent/not allowlisted; Node clients
     * send no Origin by default. Defaults to the gateway's own base origin (which
     * is typically allowlisted). Set explicitly to override.
     */
    clientOrigin?: string;
    /**
     * Advertised WS client mode (e.g. `"cli"`, `"webchat"`). Gateways bind the
     * scope-preservation and device-identity policy to the mode: a headless
     * operator client on loopback uses `"cli"` so shared-secret auth keeps its
     * operator scopes instead of being downgraded to read-only.
     */
    clientMode?: string;
    /**
     * Operator scopes to request on the WS connect handshake. Omit for the
     * gateway default (read-only). Request `operator.write` to start runs.
     */
    requestedScopes?: readonly string[];
    /** Manifest team id for this gateway instance. */
    teamId?: string;
    /** Override the auto-wired runtime capability resolver. */
    resolver?: ProviderCapabilityResolver;
    /** Extend/override the auto-wired backends. */
    backends?: CapabilityClientBackends;
    /** Override the static fallback declaration. */
    fallbackSupports?: CapabilitySupport;
};

/**
 * A manifest fetched via a loader (e.g. from a gateway). Cached after first
 * load; call refresh() to revalidate.
 */
export declare function createCachedManifestSource(loader: TeamManifestLoader): CachedTeamManifestSource;

export declare function createCapabilityClient(options: CreateCapabilityClientOptions): CapabilityClient;

export type CreateCapabilityClientOptions = {
    providerKind: string;
    runtime: RuntimeClient;
    /** Static declaration used until (or when) runtime resolution is available. */
    fallbackSupports?: CapabilitySupport;
    /** Runtime-authoritative source; transport failures degrade to the fallback. */
    resolver?: ProviderCapabilityResolver;
    backends?: CapabilityClientBackends;
    /** Which providers serve a capability — enriches the notated gap. */
    availableOn?: (key: CapabilityKey) => readonly string[];
    /**
     * Gateway streaming transport: start the run and pump canonical run-stream
     * events into the handlers. Used when the runtime client itself has no
     * `streamRun` (gateways). Wired by `createApiClient`.
     */
    streamRunBridge?: (body: StreamRunBody, handlers: RunEventStreamHandlers, options?: {
        signal?: AbortSignal;
        /** Invoked with the run id as soon as the run starts (before events). */
        onRunId?: (runId: string) => void;
    }) => Promise<void>;
    /** Extra teardown run by dispose() after the control plane is disposed. */
    onDispose?: () => Promise<void> | void;
};

export declare function createDefaultTeamManifest(options?: CreateDefaultTeamManifestOptions): TeamManifest;

export type CreateDefaultTeamManifestOptions = {
    teamId?: string;
    memberId?: string;
    workspaceRootPath?: string | null;
    workspacePaths?: readonly TeamWorkspacePathEntry[] | null;
};

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 createGatewaySseRunEventProvider(options: CreateGatewaySseRunEventProviderOptions, providerOptions?: ResolveGatewayProviderOptions): GatewaySseRunEventProvider;

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

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 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?: CreateProviderRegistryOptions<RuntimeProviderModule>): ProviderRegistry<RuntimeProviderModule>;

/** A fixed, host-provided manifest. Normalized once. */
export declare function createStaticManifestSource(manifest: TeamManifestInput): TeamManifestSource;

export declare function createSurfacePathResolver(extensionContracts?: SurfaceContractMap, baseResolver?: SurfacePathResolver): SurfacePathResolver;

export declare function createTeamRouteResolver(): TeamRouteResolver;

/** Auth headers a credential resolver contributes to a request. */
export type CredentialHeaders = Record<string, string>;

/**
 * Provider-supplied auth scheme. Returns the headers to merge onto a request.
 * Closes over whatever secret the provider needs (token, api key, cookie).
 */
export type CredentialResolver = () => CredentialHeaders;

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

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

/** The set of capability keys a provider declares supported. */
export declare function declaredCapabilities(provider: DeclaredProviderKey): CapabilityKey[];

export declare const DEFAULT_TEAM_ID: "default";

export declare const DEFAULT_TEAM_MEMBER_ID: "default-agent";

export declare const DEFAULT_TEAM_ROUTE_KEYS: readonly [
    "kanban",
    "runs",
    "config",
    "workspace"
];

export type DefaultTeamRouteKey = (typeof DEFAULT_TEAM_ROUTE_KEYS)[number];

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 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 findTeamActionContract(actions: readonly TeamActionContract[] | null | undefined, actionId: string | null | undefined): TeamActionContract | null;

export declare function findTeamManifestMember(team: ManifestTeam, memberId: string | null | undefined): ManifestMember | null;

export declare function findTeamManifestTeam(manifest: TeamManifest, teamId: string | null | undefined): ManifestTeam | null;

export declare function gapResult<T>(gap: ContractGap): CapabilityResult<T>;

export declare const GATEWAY_API_ENDPOINT_TEMPLATES: {
    readonly ecgSharedFiles: "/api/v1/files?agent={agent}&folder={folder}";
    readonly runApproval: "/v1/runs/{run_id}/approval";
};

export declare const GATEWAY_API_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;
};

export declare const GATEWAY_MEDIA_API_BASE_PATH: "/v1/media";

export declare const GATEWAY_MEDIA_API_ENDPOINTS: {
    readonly root: "/v1/media";
    readonly providers: (kind?: string | null) => string;
    readonly generate: (kind: string) => string;
    readonly job: (kind: string, jobId: string) => string;
    readonly assets: (query?: {
        kind?: string | null;
        cursor?: string | null;
        limit?: number | null;
    } | null) => string;
    readonly asset: (assetId: string) => string;
};

export declare const GATEWAY_PROBE_ENDPOINTS: {
    readonly health: "/health";
    readonly healthz: "/healthz";
    readonly readyz: "/readyz";
};

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

export declare const GATEWAY_RAW_EXTENSION: RuntimeControlExtensionDescriptor<RawGatewayChannel>;

export declare const GATEWAY_SYSTEM_RPC_METHODS: {
    readonly healthSnapshot: "health.snapshot";
    readonly health: "health";
    readonly logsTail: "logs.tail";
};

export declare const GATEWAY_WIKI_API_BASE_PATH: "/v1/wiki";

export declare const GATEWAY_WIKI_API_ENDPOINTS: {
    readonly root: "/v1/wiki";
    readonly vaults: "/v1/wiki/vaults";
    readonly vault: (vaultId: string) => string;
    readonly tree: (vaultId: string) => string;
    readonly read: (vaultId: string, path: string) => string;
    readonly ingest: (vaultId: string) => string;
    readonly compile: (vaultId: string) => string;
    readonly promote: (vaultId: string) => string;
    readonly job: (vaultId: string, jobId: string) => string;
    readonly artifact: (vaultId: string, artifactId: 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 declare class GatewayHttpError extends Error {
    readonly type = ApiClientErrorType.GatewayHttp;
    readonly status: number;
    readonly code: string | null;
    constructor(message: string, status: number, code?: string | null);
}

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 GatewayResolvedRouteBinding = {
    id: string;
    teamId: string;
    memberId: string | null;
    source: string | null;
    channel: string | null;
    actionId: string | null;
    routeKey: TeamRouteKey;
    path: string;
    metadata?: Record<string, unknown> | null;
};

export type GatewayRouteBinding = {
    id: string;
    teamId: string;
    memberId?: string | null;
    source?: string | null;
    channel?: string | null;
    actionId?: string | null;
    routeKey?: TeamRouteKey | null;
    sessionKeyPattern?: string | null;
    metadata?: Record<string, unknown> | null;
};

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 declare function getBrowserWindowOrigin(): string | null;

export declare function getErrorCode(error: unknown): string | undefined;

export declare function getErrorMessage(error: unknown, fallbackMessage?: string): string;

/**
 * HTTP status carried by a typed transport error (`HttpApiError`,
 * `GatewayHttpError`, or any error exposing a numeric `status`). `undefined`
 * for non-HTTP failures (transport, abort, RPC) so callers branch on the value,
 * never on the message string.
 */
export declare function getErrorStatus(error: unknown): number | undefined;

export declare function getErrorType(error: unknown): string | undefined;

export declare function getRuntimeErrorMetadata(error: unknown): RuntimeErrorMetadata | undefined;

export declare function getRuntimeProviderCapabilityRow(provider: string): RuntimeProviderCapabilityRow | undefined;

export declare function getTransportErrorMetadata(error: unknown): TransportErrorMetadata | undefined;

export declare const GLOBAL_REPO_ROOT_KEY: "__CAVI_REPO_ROOT__";

export declare const HERMES_API_ENDPOINT_TEMPLATES: {
    readonly ecgSharedFiles: "/api/v1/files?agent={agent}&folder={folder}";
    readonly runApproval: "/v1/runs/{run_id}/approval";
};

export declare const HERMES_API_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;
};

export declare const HERMES_MEDIA_API_ENDPOINTS: {
    readonly root: "/v1/media";
    readonly providers: (kind?: string | null) => string;
    readonly generate: (kind: string) => string;
    readonly job: (kind: string, jobId: string) => string;
    readonly assets: (query?: {
        kind?: string | null;
        cursor?: string | null;
        limit?: number | null;
    } | null) => string;
    readonly asset: (assetId: string) => string;
};

export declare const HERMES_WIKI_API_ENDPOINTS: {
    readonly root: "/v1/wiki";
    readonly vaults: "/v1/wiki/vaults";
    readonly vault: (vaultId: string) => string;
    readonly tree: (vaultId: string) => string;
    readonly read: (vaultId: string, path: string) => string;
    readonly ingest: (vaultId: string) => string;
    readonly compile: (vaultId: string) => string;
    readonly promote: (vaultId: string) => string;
    readonly job: (vaultId: string, jobId: string) => string;
    readonly artifact: (vaultId: string, artifactId: string) => string;
};

export type HttpApiClientAuth = {
    bearerToken?: string | null;
    clientId?: string | null;
    /**
     * Provider-supplied auth scheme. When present, its headers replace the
     * default bearer Authorization header. See core/http/credentials.ts.
     */
    resolveHeaders?: CredentialResolver;
};

export type HttpApiClientOptions = {
    baseUrl: string;
    basePath?: string;
    allowRelativeBaseUrl?: boolean;
    defaultHeaders?: Record<string, string>;
    /** Send the X-Portal-Client-Id header. Default true; set false for non-gateway backends. */
    includePortalClientIdHeader?: boolean;
    auth?: HttpApiClientAuth;
    defaultTimeoutMs?: number;
    fetchImpl?: typeof fetch;
    cache?: RequestCache;
    credentials?: RequestCredentials;
    onTrace?: (trace: HttpApiTrace) => void;
};

export type HttpApiClientSurface = string;

export declare class HttpApiError extends Error {
    readonly type = ApiClientErrorType.Http;
    readonly code = ApiClientErrorCode.HttpRequestFailed;
    readonly path: string;
    readonly url: string;
    readonly method: HttpApiHttpMethod;
    readonly status: number;
    readonly body: string;
    constructor(params: {
        message: string;
        path: string;
        url: string;
        method: HttpApiHttpMethod;
        status: number;
        body: string;
    });
}

export type HttpApiHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

export type HttpApiRequestInit = {
    method?: HttpApiHttpMethod;
    body?: unknown;
    rawBody?: BodyInit;
    headers?: Record<string, string>;
    signal?: AbortSignal;
    timeoutMs?: number;
    idempotencyKey?: string;
    cache?: RequestCache;
    credentials?: RequestCredentials;
};

export type HttpApiTrace = {
    at: number;
    surface: HttpApiClientSurface;
    method: HttpApiHttpMethod;
    path: string;
    url: string;
    ok: boolean;
    status?: number;
    durationMs: number;
    error?: string;
};

export type HttpApiTransport = <TResponse>(path: string, init?: HttpApiRequestInit) => Promise<TResponse>;

export declare const IDEMPOTENCY_KEY_HEADER: "Idempotency-Key";

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

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

/**
 * True when an error is an authentication/authorization failure (HTTP 401/403,
 * or a synthesized `Auth`-typed/`auth_required`/`auth_forbidden` error). Use
 * this to trigger token refresh or re-auth instead of inspecting `.status`
 * inline at every call site.
 */
export declare function isAuthError(error: unknown): boolean;

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

/**
 * True when an error is a synthesized `EndpointNotFound` failure — the
 * everyday cross-provider branch for a surface a provider declares
 * unsupported (Gemini `getRun`/`cancelRun`, OpenClaw wiki/media).
 */
export declare function isEndpointNotFoundError(error: unknown): boolean;

export declare function isGatewayHttpError(error: unknown): error is GatewayHttpError;

export declare function isHttpApiError(error: unknown): error is HttpApiError;

export declare function liveResult<T>(data: T): CapabilityResult<T>;

export type ManifestIdentity = {
    name?: string | null;
    displayName?: string | null;
    slug?: string | null;
    code?: string | null;
    aliases?: readonly string[] | null;
    /** Host/domain-specific identity hints (e.g. CAVI portalId/sector). Agnostic core never reads these. */
    metadata?: Record<string, unknown> | null;
};

export type ManifestMember = {
    id: string;
    identity?: ManifestIdentity | null;
    workspace?: TeamWorkspaceConfig | null;
    actions?: readonly TeamActionContract[] | null;
    capabilities?: readonly string[] | null;
    metadata?: Record<string, unknown> | null;
};

export type ManifestRouteConfig = {
    key: string;
    path?: string | null;
};

export type ManifestTeam = {
    id: string;
    identity?: ManifestIdentity | null;
    members?: readonly ManifestMember[] | null;
    workspace?: TeamWorkspaceConfig | null;
    actions?: readonly TeamActionContract[] | null;
    capabilities?: readonly string[] | null;
    routes?: readonly ManifestRouteConfig[] | null;
    metadata?: Record<string, unknown> | null;
};

/** Project a manifest team onto the provider-agnostic core `Team`. */
export declare function manifestTeamToTeam(team: ManifestTeam): Team;

/**
 * Merge a runtime-resolved support map over the static fallback: runtime keys
 * win; the fallback fills whatever the runtime response did not mention. This
 * realizes "runtime authoritative, static fallback" for capability presence —
 * a static OpenClaw default that gates media/wiki off flips them on for an
 * instance whose capabilities endpoint reports them supported.
 */
export declare function mergeCapabilitySupport(fallback: CapabilitySupport, runtime: CapabilitySupport): CapabilitySupport;

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

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

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

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 declare function normalizeTeamManifest(manifest: Partial<TeamManifest> | null | undefined): TeamManifest;

export declare const PORTAL_CLIENT_ID_HEADER: "X-Portal-Client-Id";

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

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

export declare const PROVIDER_CAPABILITIES: {
    readonly claude: Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
    readonly "claude-managed-agents": Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
    readonly codex: Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
    readonly gemini: Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
    readonly agy: Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
    readonly hermes: Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
    readonly openclaw: Partial<Record<"runs" | "streaming" | "media" | "wiki" | "agentConfig" | "teams" | "kanban" | "workspace" | "operator" | "discourse" | "batch" | "authStatus" | "sessions" | "models" | "usage" | "tasks" | "events", boolean>>;
};

/**
 * A gateway provider supplies one of these: fetch its capabilities endpoint
 * and transform it into the unified shape. Runtime-only providers without a
 * capabilities endpoint omit it, and the static fallback is used unchanged.
 */
export type ProviderCapabilityResolver = (options?: {
    signal?: AbortSignal;
}) => Promise<ResolvedProviderCapabilities>;

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

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 const REPO_ROOT_ENV_KEY: "REPO_ROOT";

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

export declare function requireRepoRoot(options?: ResolveRepoRootOptions): string;

/**
 * The runtime-resolved capability + path picture for a live provider instance,
 * produced by fetching the provider's capabilities endpoint and transforming
 * the response. This is the AUTHORITATIVE source (design decision M1):
 *
 * - `supports` overrides the static `PROVIDER_CAPABILITIES` fallback, because
 *   capability presence is plugin/runtime dependent (e.g. OpenClaw media/wiki
 *   are gated off pre-plugin but live once the plugin is installed).
 * - `manifest` drives dynamic path resolution — members are agents, actions
 *   carry their real `route.path` — so no agent name (`machine`, `martina`,
 *   `deb`, …) or endpoint literal is ever hardcoded in the package.
 */
export interface ResolvedProviderCapabilities {
    providerKind: string;
    supports: CapabilitySupport;
    manifest: TeamManifest;
}

/** True iff, after merging runtime over fallback, the provider supports `key`. */
export declare function resolvedSupports(fallback: CapabilitySupport, runtime: CapabilitySupport | undefined, key: CapabilityKey): boolean;

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 resolveGatewayRouteBinding(manifest: TeamManifest, options: ResolveGatewayRouteBindingOptions): GatewayResolvedRouteBinding | null;

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

export declare function resolvePath(key: string, params?: Record<string, string>): string;

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

export declare function resolveRepoRoot(options?: ResolveRepoRootOptions): string | null;

export type ResolveRepoRootOptions = {
    repoRoot?: string | null;
    env?: RepoRootEnv;
    globalRepoRoot?: string | null;
};

export declare function resolveSurfaceContractPath(contract: SurfaceContract, params?: Record<string, string>): string;

export declare function resolveTeamActionApiPath(manifest: TeamManifest, teamId: string | null | undefined, actionId: string | null | undefined, options?: ResolveTeamActionContractOptions): string;

export declare function resolveTeamActionContract(manifest: TeamManifest, teamId: string | null | undefined, actionId: string | null | undefined, options?: ResolveTeamActionContractOptions): TeamActionContract;

export type ResolveTeamActionContractOptions = {
    memberId?: string | null;
    /** Values substituted into `{token}` placeholders in the action's route path. */
    params?: Record<string, string | number | boolean> | null;
    /** Query parameters appended to the resolved path (via `appendHttpQuery`). */
    query?: Record<string, string | number | boolean | undefined> | null;
};

export declare function resolveTeamRoutePath(routeKey: TeamRouteKey, options: ResolveTeamRoutePathOptions): string;

export type ResolveTeamRoutePathOptions = {
    teamId: string;
    actionId?: string | null;
    agentId?: string | null;
    workspacePath?: string | null;
};

export declare function resolveTeamWorkspaceApiPath(team: ManifestTeam, keyOrPath: string, options?: ResolveTeamWorkspacePathOptions): string;

export declare function resolveTeamWorkspacePath(team: ManifestTeam, keyOrPath: string, options?: ResolveTeamWorkspacePathOptions): string;

export type ResolveTeamWorkspacePathOptions = {
    memberId?: string | null;
};

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>;
};

/**
 * 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>;
}