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

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

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;

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

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

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" | "unknown";

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

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

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

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

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 type ProviderRegistry<M extends RuntimeProviderModule = GatewayProviderModule> = RuntimeProviderRegistry<M>;

export declare const REPO_ROOT_ENV_KEY: "REPO_ROOT";

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

export declare function requireRepoRoot(options?: ResolveRepoRootOptions): 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 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. */
    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 RunStreamEvent = RunStreamMessageDeltaEvent | RunStreamRunCompletedEvent | RunStreamRunFailedEvent | RunStreamRunCancelledEvent | RunStreamApprovalRequestEvent | RunStreamToolEvent;

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

/** 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 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-only surfaces (teams/kanban/workspace/operator) live on
 * `GatewayClient`, which extends this.
 */
export interface RuntimeClient {
    getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
    startRun(body: RuntimeRunStartBody): Promise<RuntimeRunStatus>;
    /**
     * Optional — synchronous/stateless providers (e.g. Claude SDK) omit these.
     * Consumers should null-check (`client.cancelRun?.(id)`) or gate on
     * `RuntimeCapabilities`. Providers that expose the method but can't serve it
     * should throw `ApiClientError(EndpointNotFound)`.
     */
    getRun?(runId: string): Promise<RuntimeRunStatus>;
    cancelRun?(runId: string): Promise<{
        status: string;
    }>;
    /**
     * Start a run and stream it as canonical RunStreamEvents. Optional: providers
     * that use a subscribe-by-runId model (gateways) omit this and expose a
     * RunEventStreamProvider 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">;

/** @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 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 declare function runtimeSupports(capabilities: RuntimeCapabilities, surface: RuntimeSurface): boolean;

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

/** 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 type SerializedApiClientError = {
    name: string;
    message: string;
    type?: string;
    code?: string;
};

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

export declare function stringifyUnknownError(error: unknown): string;

export declare const SURFACE_CONTRACTS: Record<string, SurfaceContract>;

export type SurfaceContract = {
    key: string;
    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
    path: (params?: Record<string, string>) => string;
    degradation: "hard" | "gap" | "silent";
    owner: string;
    note: string;
};

export type SurfaceContractMap = Record<string, SurfaceContract>;

export type SurfacePathResolver = (key: string, params?: Record<string, string>) => string;

export declare const TEAM_ACTION_INPUT_MODES: readonly [
    "command",
    "json",
    "text"
];

export declare const TEAM_ACTION_OUTPUT_MODES: readonly [
    "artifact",
    "json",
    "markdown",
    "text"
];

export declare const TEAM_MANIFEST_VERSION: 1;

export type TeamActionArtifact = {
    key: string;
    contentType?: string | null;
    path?: string | null;
    url?: string | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamActionArtifactContract = {
    key: string;
    contentType?: string | null;
    path?: string | null;
    description?: string | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamActionContract = {
    id: string;
    title?: string | null;
    description?: string | null;
    enabled?: boolean | null;
    route?: TeamActionRouteContract | null;
    input?: TeamActionInputContract | null;
    output?: TeamActionOutputContract | null;
    defaults?: Record<string, TeamActionJsonValue> | null;
    capabilities?: readonly string[] | null;
    metadata?: Record<string, unknown> | null;
};

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

export type TeamActionInputContract = {
    mode?: TeamActionInputMode | null;
    command?: string | null;
    params?: readonly TeamActionParamContract[] | null;
    schema?: Record<string, unknown> | null;
    examples?: readonly string[] | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamActionInputMode = (typeof TEAM_ACTION_INPUT_MODES)[number];

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

export type TeamActionOutputContract = {
    mode?: TeamActionOutputMode | null;
    contentType?: string | null;
    schema?: Record<string, unknown> | null;
    artifacts?: readonly TeamActionArtifactContract[] | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamActionOutputMode = (typeof TEAM_ACTION_OUTPUT_MODES)[number];

export type TeamActionParamContract = {
    key: string;
    type?: TeamActionParamType | null;
    required?: boolean | null;
    default?: TeamActionJsonValue;
    values?: readonly string[] | null;
    aliases?: readonly string[] | null;
    description?: string | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamActionParamType = "boolean" | "enum" | "file" | "json" | "number" | "string";

export type TeamActionResponse = (TeamActionResponseBase & {
    kind: "artifact";
    artifacts: readonly TeamActionArtifact[];
    data?: TeamActionJsonValue;
}) | (TeamActionResponseBase & {
    kind: "json";
    data: TeamActionJsonValue;
}) | (TeamActionResponseBase & {
    kind: "markdown";
    markdown: string;
}) | (TeamActionResponseBase & {
    kind: "text";
    text: string;
});

export type TeamActionResponseBase = {
    actionId?: string | null;
    teamId?: string | null;
    memberId?: string | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamActionRouteContract = {
    method?: TeamActionHttpMethod | null;
    surfaceKey?: string | null;
    path?: string | null;
    metadata?: Record<string, unknown> | null;
};

export type TeamManifest = {
    version: TeamManifestVersion;
    actions?: readonly TeamActionContract[] | null;
    bindings?: readonly GatewayRouteBinding[] | null;
    teams: readonly ManifestTeam[];
};

export type TeamManifestInput = Partial<TeamManifest> | null | undefined;

export type TeamManifestLoader = () => TeamManifestInput | Promise<TeamManifestInput>;

/** The seam through which a host supplies its manifest to the package. */
export interface TeamManifestSource {
    getManifest(): Promise<TeamManifest>;
}

export type TeamManifestVersion = typeof TEAM_MANIFEST_VERSION;

export type TeamRouteKey = DefaultTeamRouteKey | "action" | "agent.action" | "agent.config" | "agent.workspace" | (string & {});

/**
 * Generic, host-overridable route resolution over a TeamManifest. The default
 * implementation delegates to the standard REST path builders.
 */
export interface TeamRouteResolver {
    resolveRoutePath(routeKey: TeamRouteKey, options: ResolveTeamRoutePathOptions): string;
    resolveActionApiPath(manifest: TeamManifest, teamId: string, actionId: string, options?: ResolveTeamActionContractOptions): string;
    resolveWorkspaceApiPath(manifest: TeamManifest, teamId: string, keyOrPath: string, options?: ResolveTeamWorkspacePathOptions): string;
    resolveBinding(manifest: TeamManifest, options: ResolveGatewayRouteBindingOptions): GatewayResolvedRouteBinding | null;
}

export type TeamWorkspaceConfig = {
    rootPath: string;
    paths?: readonly TeamWorkspacePathEntry[] | null;
};

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

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

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

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