@cavi-ai/api-client/providers/hermes

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

export declare function buildAgentConfigFromHermesWebuiSnapshot(input: {
    agentId: string;
    profile?: AgentProfileSummary | null;
    profiles?: unknown;
    config?: unknown;
    schema?: unknown;
    defaults?: unknown;
    models?: unknown;
    reasoning?: unknown;
    mcpServers?: unknown;
    fetchedAt?: number;
    etag?: string;
}): AgentConfig;

export declare function createHermesApiServerControlPlane(options: RequestOptions): {
    probe(): Promise<void>;
    models: ModelCatalogClient;
    sessions: SessionClient;
    usage: UsageClient;
};

export declare function createHermesApiServerEventClient(options: HermesApiServerRunEventsOptions): HermesApiServerEventClient;

export declare function createHermesAuthStatusClient(rest: HermesDashboardRestClient): AuthStatusClient;

/**
 * Build the runtime capability resolver for a Hermes API server: GET the
 * capabilities endpoint and transform the envelope into the unified shape.
 * The result is authoritative over the static fallback (design decision M1).
 */
export declare function createHermesCapabilityResolver(options: CreateHermesCapabilityResolverOptions): ProviderCapabilityResolver;

export type CreateHermesCapabilityResolverOptions = {
    baseUrl: string;
    token?: string;
    fetchImpl?: typeof fetch;
    /** Manifest team id for this gateway instance. Defaults to the provider kind. */
    teamId?: string;
};

export declare function createHermesDashboardJsonRpcClient(options: HermesDashboardJsonRpcOptions): HermesDashboardJsonRpcClient;

export declare function createHermesDashboardRestClient(options: HermesDashboardRestOptions): HermesDashboardRestClient;

/**
 * Adapt the Hermes kanban plugin's REST surface to the provider-agnostic
 * KanbanClient — the same contract `createOpenClawKanbanClient` satisfies from
 * Workboard RPC.
 */
export declare function createHermesKanbanClient(request: HermesKanbanRequest, options?: HermesKanbanClientOptions): KanbanClient;

export declare function createHermesModelCatalogClient(rest: HermesDashboardRestClient): ModelCatalogClient;

export declare function createHermesRawGatewayChannel(rpc: HermesDashboardJsonRpcClient, lifecycle: HermesRawGatewayLifecycle): RawGatewayChannel;

export declare function createHermesRuntimeEventClient(rpc: HermesDashboardJsonRpcClient): RuntimeEventClient;

export declare function createHermesSessionClient(operations: GatewaySessionOperations): SessionClient;

export declare function createHermesSessionOperations(options: {
    rpc: HermesDashboardJsonRpcClient;
    rest: HermesDashboardRestClient;
}): GatewaySessionOperations;

export declare function createHermesTeamRegistry(config?: TeamRegistryConfig): TeamRegistry;

export declare function createHermesUsageClient(options: HermesUsageClientOptions): UsageClient;

export type GatewayChatRunAttachment = HermesChatRunAttachment;

export type GatewayRouteMetadata = HermesRouteMetadata;

export type GatewayRouteSource = HermesRouteSource;

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

export declare const GatewaySseRunEventProvider: typeof CoreGatewaySseRunEventProvider;

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

export declare const HERMES_DASHBOARD_PATHS: {
    readonly sessions: "/api/sessions";
    readonly session: (id: string) => string;
    readonly usage: "/api/analytics/usage";
    readonly models: "/api/models";
    readonly providerAuth: "/api/provider-auth";
    readonly profile: "/api/profile";
    readonly config: "/api/config";
};

export declare const HERMES_DASHBOARD_REST_FALLBACKS: {
    readonly listSessions: "session.list";
    readonly getUsage: "session.usage";
};

export declare const HERMES_HTTP_API_ENV_ALIASES: {
    readonly baseUrl: readonly [
        "EXPO_PUBLIC_HERMES_API_BASE_URL",
        "VITE_HERMES_API_BASE_URL",
        "GATEWAY_API_BASE_URL",
        "EXPO_PUBLIC_GATEWAY_API_BASE_URL",
        "VITE_GATEWAY_API_BASE_URL"
    ];
    readonly authToken: readonly [
        "EXPO_PUBLIC_HERMES_API_AUTH_TOKEN",
        "VITE_HERMES_API_AUTH_TOKEN",
        "GATEWAY_API_AUTH_TOKEN",
        "EXPO_PUBLIC_GATEWAY_TOKEN",
        "EXPO_PUBLIC_GATEWAY_API_AUTH_TOKEN",
        "VITE_GATEWAY_API_AUTH_TOKEN"
    ];
    readonly clientId: readonly [
        "EXPO_PUBLIC_HERMES_API_CLIENT_ID",
        "VITE_HERMES_API_CLIENT_ID",
        "GATEWAY_API_CLIENT_ID",
        "EXPO_PUBLIC_GATEWAY_CLIENT_ID",
        "EXPO_PUBLIC_GATEWAY_API_CLIENT_ID",
        "VITE_GATEWAY_API_CLIENT_ID"
    ];
};

export declare const HERMES_HTTP_API_ENV_KEYS: {
    readonly baseUrl: "HERMES_API_BASE_URL";
    readonly authToken: "HERMES_API_AUTH_TOKEN";
    readonly clientId: "HERMES_API_CLIENT_ID";
};

/** Cookie the Hermes host-config plugin reads to select the active profile. */
export declare const HERMES_PROFILE_COOKIE_NAME = "hermes_profile";

export declare const HERMES_PROVIDER_MODULE: GatewayProviderModule;

export declare class HermesAgentConfigApiClient extends GatewayAgentConfigApiClient {
    constructor(options: HttpApiClientOptions);
    getProfileConfig(agentId: string): Promise<AgentConfig>;
    private getProfileConfigViaHermesWebui;
    patchProfileConfig(agentId: string, diff: AgentConfigDraftDiff, options?: PatchProfileConfigOptions): Promise<AgentConfig>;
    private patchProfileConfigViaHermesWebui;
}

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

export interface HermesApiServerEventClient extends RuntimeEventClient {
    dispose(): Promise<void>;
}

export type HermesApiServerRunEventsOptions = Readonly<{
    runId: string;
    sessionKey: string;
    clientId: string;
    baseUrl: string;
    token: string | null;
    fetchImpl?: typeof fetch;
}>;

export type HermesCaviCostHistorySource = Readonly<{
    getCostHistory(range: CostHistoryRange): Promise<CostHistorySnapshot>;
    range: CostHistoryRange;
    currency: string;
    accountingAuthority: string;
}>;

/**
 * A file sent with a chat turn. Base64 keeps it on the HTTP run path (gateway
 * field names are sent in snake AND camel case so the server can read whichever
 * casing it accepts).
 */
export type HermesChatRunAttachment = {
    name: string;
    mimeType: string;
    size: number;
    /** Base64-encoded file bytes (no data: prefix). */
    dataBase64: string;
};

export type HermesDashboardDeleteResult = Readonly<{
    ok: true;
}>;

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

export interface HermesDashboardJsonRpcClient {
    request<T>(method: string, params?: unknown, options?: RequestOptions): Promise<T>;
    subscribe(listener: (event: HermesDashboardEvent) => void): () => void;
    dispose(): Promise<void>;
}

export type HermesDashboardJsonRpcOptions = Readonly<{
    channel: TransportMessageChannel<unknown>;
    ownsChannel?: boolean;
    maxPendingRequests?: number;
    onProtocolError?: (error: TransportError) => void;
}>;

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

export type HermesDashboardModels = Readonly<{
    providers: readonly JsonRecord[];
}> & JsonRecord;

export type HermesDashboardObject = Readonly<Record<string, HermesDashboardJsonValue>>;

export type HermesDashboardProviderAuth = Readonly<{
    providers: readonly JsonRecord[];
}> & JsonRecord;

export interface HermesDashboardRestClient {
    listSessions(options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardSessions>;
    getSession(id: string, options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardSession>;
    deleteSession(id: string, options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardDeleteResult>;
    getUsage(options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardUsage>;
    getModels(options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardModels>;
    getProviderAuth(options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardProviderAuth>;
    getProfile(options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardObject>;
    getConfig(options?: {
        signal?: AbortSignal;
    }): Promise<HermesDashboardObject>;
}

export interface HermesDashboardRestFallback {
    request<T>(method: string, params?: unknown, options?: {
        signal?: AbortSignal;
    }): Promise<T>;
}

export type HermesDashboardRestOptions = Readonly<{
    baseUrl: string;
    authToken: string | null;
    defaultHeaders?: Record<string, string>;
    resolveAuthHeaders?: CredentialResolver;
    fetchImpl?: typeof fetch;
    fallback?: HermesDashboardRestFallback;
}>;

export type HermesDashboardSession = Readonly<{
    id: string;
    source: string | null;
    model: string | null;
}> & JsonRecord;

export type HermesDashboardSessions = Readonly<{
    sessions: readonly JsonRecord[];
    total: number;
    limit: number;
    offset: number;
}> & JsonRecord;

export type HermesDashboardUsage = Readonly<{
    daily: readonly JsonRecord[];
    by_model: readonly JsonRecord[];
    totals: JsonRecord;
    period_days: number;
    skills: JsonRecord;
}> & JsonRecord;

export type HermesKanbanClientOptions = {
    /** Board slug; omitted means the plugin's active board. */
    boardId?: string;
};

/** JSON transport for the kanban plugin's REST surface. */
export type HermesKanbanRequest = <T>(path: string, init?: {
    method?: "GET" | "POST" | "PATCH" | "DELETE";
    body?: unknown;
}) => Promise<T>;

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

export type HermesRawGatewayLifecycle = Readonly<{
    connect: () => Promise<void>;
    getConnectionState: () => RawGatewayConnectionState;
    onConnectionState: (listener: (state: RawGatewayConnectionState) => void) => () => void;
    dispose?: () => void | Promise<void>;
}>;

/**
 * Provider-neutral metadata bag attached to a Hermes chat run. Free-form by
 * design — the gateway forwards untyped fields to route handlers. Use
 * {@link sanitizeHermesRouteMetadata} before sending to strip dict-valued
 * route binding keys some routers reject as malformed.
 */
export type HermesRouteMetadata = Record<string, unknown>;

export type HermesRouteSource = Record<string, unknown>;

/**
 * Subscribes to the Hermes run-event SSE stream and emits
 * canonical run-stream events. Falls back to status polling
 * when SSE is unsupported by the server.
 *
 * The caller is responsible for starting the run and
 * supplying the resulting `run_id` to {@link subscribe}.
 *
 * Tool events are emitted when the underlying Hermes payload contains
 * tool-shaped fields (`tool_name`, `function_name`, etc.). When the Hermes API
 * does not natively emit tool events, compose this provider with
 * {@link RunPreviewPollProvider} via `createRunStreamWithToolFallback`.
 */
export declare class HermesSseRunEventProvider extends CoreGatewaySseRunEventProvider {
    constructor(options: HermesSseRunEventProviderOptions);
}

export type HermesSseRunEventProviderOptions = GatewaySseRunEventProviderOptions & {
    /** Required for `X-Hermes-Session-Key` on both the SSE request and the poll fallback. */
    sessionKey: string;
};

export type HermesUsageClientOptions = Readonly<{
    rest: HermesDashboardRestClient;
    caviCostHistory?: HermesCaviCostHistorySource;
}>;

export declare const MAX_HERMES_SESSION_PAGE_SIZE = 200;

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

export declare function requireHermesSafeJsonRecord(value: unknown, label: string): Record<string, unknown>;

export declare const resolveGatewayChatRunApproval: typeof resolveHermesChatRunApproval;

export type ResolveGatewayChatRunApprovalParams = ResolveHermesChatRunApprovalParams;

export declare const resolveGatewayRouteSource: typeof resolveHermesRouteSource;

/**
 * Resolves a pending approval gate through the configured run approval endpoint with
 * one of the canonical {@link RunStreamApprovalChoice} options.
 */
export declare function resolveHermesChatRunApproval(params: ResolveHermesChatRunApprovalParams): Promise<void>;

export type ResolveHermesChatRunApprovalParams = {
    httpBase: string;
    authToken: string;
    clientId: string;
    headers?: Record<string, string>;
    runId: string;
    choice: RunStreamApprovalChoice;
    sessionKey?: string;
    signal?: AbortSignal;
    fetchImpl?: typeof fetch;
};

export declare function resolveHermesHttpApiConfigFromEnv(env: HttpApiEnvSource, options?: ResolveHermesHttpApiConfigOptions): HttpApiSurfaceConfig;

export type ResolveHermesHttpApiConfigOptions = {
    defaults?: Partial<HttpApiSurfaceConfig>;
    trimValues?: boolean;
    includeAliases?: boolean;
};

export declare function resolveHermesRouteSource(input: {
    clientId: string;
    sessionKey: string;
    targetProfile?: string;
    targetAgent?: string;
    harness?: string;
    source?: HermesRouteSource;
    routeChannel?: RouteChannelConfig;
}): HermesRouteSource | undefined;

/**
 * Host-supplied route-channel policy. The provider knows no product agents; a
 * consumer maps its own default channel and agent→channel overrides (e.g. CAVI
 * passes `{ defaultChannel: "front-door", agentChannelOverrides: { tony: "front-door" } }`).
 */
export type RouteChannelConfig = {
    defaultChannel?: string;
    agentChannelOverrides?: Record<string, string>;
};

export declare const sanitizeGatewayRouteMetadata: typeof sanitizeHermesRouteMetadata;

export declare const sanitizeGatewayRouteSource: typeof sanitizeHermesRouteSource;

/**
 * Gateway route bindings are scalar fields (`targetProfile`, `targetAgent`,
 * `sessionKey`, `action`). Some routers validate dict-valued `binding` /
 * `routeBinding` keys and reject the whole chat turn — strip those before
 * forwarding metadata.
 */
export declare function sanitizeHermesRouteMetadata(metadata: HermesRouteMetadata | undefined): HermesRouteMetadata | undefined;

export declare function sanitizeHermesRouteSource(source: HermesRouteSource | undefined): HermesRouteSource | undefined;

export declare const startGatewayChatRun: typeof startHermesChatRun;

export type StartGatewayChatRunParams = StartHermesChatRunParams;

/**
 * Starts a Hermes chat run through the configured run endpoint. Sends route binding fields in
 * both snake AND camel case for cross-version gateway compatibility. Sanitizes
 * metadata via {@link sanitizeHermesRouteMetadata} before forwarding.
 *
 * Returns the new `run_id`. Pair with {@link HermesSseRunEventProvider} or
 * {@link streamHermesChatRun} to consume the event stream.
 */
export declare function startHermesChatRun(params: StartHermesChatRunParams): Promise<{
    runId: string;
}>;

export type StartHermesChatRunParams = {
    httpBase: string;
    authToken: string;
    clientId: string;
    headers?: Record<string, string>;
    input: string;
    sessionId: string;
    /** Defaults to {@link sessionId} when omitted. */
    sessionKey?: string;
    targetProfile?: string;
    targetAgent?: string;
    action?: string;
    harness?: string;
    source?: HermesRouteSource;
    /** Host-supplied default/agent channel mapping (the provider bakes in none). */
    routeChannel?: RouteChannelConfig;
    metadata?: HermesRouteMetadata;
    attachments?: readonly HermesChatRunAttachment[];
    signal?: AbortSignal;
    fetchImpl?: typeof fetch;
};

export declare const streamGatewayChatRun: typeof streamHermesChatRun;

export type StreamGatewayChatRunParams = StreamHermesChatRunParams;

export type StreamGatewayChatRunResult = StreamHermesChatRunResult;

/**
 * Canonical orchestrator: starts a Hermes chat run, subscribes to its event
 * stream via {@link HermesSseRunEventProvider}, and optionally stitches in
 * tool events from the post-hoc run preview via
 * {@link createRunStreamWithToolFallback}. Consumers receive canonical
 * {@link RunStreamEvent}s on `onEvent` — switch on `event.event` against
 * {@link RUN_STREAM_EVENT_NAMES}, never inline strings.
 */
export declare function streamHermesChatRun(params: StreamHermesChatRunParams): Promise<StreamHermesChatRunResult>;

export type StreamHermesChatRunParams = StartHermesChatRunParams & {
    onEvent: (event: RunStreamEvent) => void;
    /**
     * Optional snapshot fetcher — when present, composes a tool-event fallback
     * via {@link RunPreviewPollProvider} so tool calls land in the stream even
     * when the Hermes SSE doesn't surface them. Once Hermes SSE catches up on
     * tool events, the fallback becomes a no-op automatically.
     */
    fetchToolEventSnapshot?: RunPreviewSnapshotFetcher;
};

export type StreamHermesChatRunResult = {
    /**
     * True when at least one terminal lifecycle event was observed (delta /
     * completed / failed / cancelled). Callers use this to detect a silent
     * stream (no response) and trigger a fallback transport.
     */
    sawAssistantResponseEvent: boolean;
};

export declare const TEAM_REGISTRY_CONFIG: TeamRegistryConfig;

export type TeamRegistryConfig = {
    provider?: TeamRegistryProviderKind | null;
    manifest?: Partial<TeamManifest> | null;
    teams?: readonly TeamRegistryTeamConfig[] | null;
    libraries?: TeamRegistryLibraryConfig | null;
    snapshot?: Pick<OperatorRegistrySnapshot, "teams"> | null;
};

export declare function transformHermesCapabilities(payload: unknown, options?: TransformHermesCapabilitiesOptions): ResolvedProviderCapabilities;

export type TransformHermesCapabilitiesOptions = {
    /** Manifest team id for this gateway instance. Defaults to the provider kind. */
    teamId?: string;
};