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

/**
 * Build the runtime capability resolver for an OpenClaw gateway: read the
 * retained hello-ok handshake (connecting first when the source can) and
 * transform it into the unified shape. The result is authoritative over the
 * static fallback (design decision M1).
 */
export declare function createOpenClawCapabilityResolver(source: OpenClawHelloSource, options?: CreateOpenClawCapabilityResolverOptions): ProviderCapabilityResolver;

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

/** Adapt an OpenClaw Workboard RPC client to the provider-agnostic KanbanClient. */
export declare function createOpenClawKanbanClient(rpc: OpenClawWorkboardRpc): KanbanClient;

export declare function createOpenClawRuntimeControlClient(options?: OpenClawRuntimeControlClientOptions): Promise<RuntimeControlClient>;

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

export declare function createOpenClawWorkboardRpc(transport: OpenClawRpcTransport): OpenClawWorkboardRpc;

/**
 * Map the OpenClaw `agents.list` RPC payload onto the unified profile summary.
 * Verified live (2026-07-23): `{ defaultId, mainKey, scope, agents: [{ id,
 * name, workspace, agentRuntime, ... }] }`.
 */
export declare function normalizeOpenClawAgentProfiles(payload: unknown): AgentProfileSummary[];

/**
 * The advertised subset of OpenClaw RPC methods — `hello-ok.features.methods`
 * filtered by `advertise !== false` in the upstream registry.
 */
export declare const OPENCLAW_CORE_RPC_METHODS: readonly string[];

/**
 * Manifest-time baseline capabilities. The real capability snapshot for a
 * connected gateway comes from the `hello-ok` WebSocket handshake — this blob
 * is the offline fallback when no live connection exists yet.
 */
export declare const OPENCLAW_DEFAULT_CAPABILITIES: OpenClawCapabilities;

export declare const OPENCLAW_MANIFEST: ProviderManifest;

export declare const OPENCLAW_PROVIDER_MODULE: GatewayProviderModule;

/**
 * Camel-keyed lookup table of every OpenClaw RPC method (`chatSend → "chat.send"`).
 * Derived from `OPENCLAW_MANIFEST.rpc`; never define a new method string here.
 */
export declare const OPENCLAW_RPC_METHODS: RpcMethodTable;

export declare const OPENCLAW_WORKBOARD_PRIORITIES: readonly [
    "low",
    "normal",
    "high",
    "urgent"
];

export declare const OPENCLAW_WORKBOARD_RPC_METHODS: {
    readonly cardsList: "workboard.cards.list";
    readonly cardsCreate: "workboard.cards.create";
    readonly cardsUpdate: "workboard.cards.update";
    readonly cardsMove: "workboard.cards.move";
    readonly cardsDelete: "workboard.cards.delete";
    readonly cardsComment: "workboard.cards.comment";
    readonly cardsLink: "workboard.cards.link";
    readonly cardsLinkDependency: "workboard.cards.linkDependency";
    readonly cardsProof: "workboard.cards.proof";
    readonly cardsArtifact: "workboard.cards.artifact";
    readonly cardsClaim: "workboard.cards.claim";
    readonly cardsHeartbeat: "workboard.cards.heartbeat";
    readonly cardsRelease: "workboard.cards.release";
    readonly cardsPromote: "workboard.cards.promote";
    readonly cardsReassign: "workboard.cards.reassign";
    readonly cardsReclaim: "workboard.cards.reclaim";
    readonly cardsComplete: "workboard.cards.complete";
    readonly cardsBlock: "workboard.cards.block";
    readonly cardsUnblock: "workboard.cards.unblock";
    readonly cardsBulk: "workboard.cards.bulk";
    readonly cardsDiagnostics: "workboard.cards.diagnostics";
    readonly cardsDiagnosticsRefresh: "workboard.cards.diagnostics.refresh";
    readonly cardsDispatch: "workboard.cards.dispatch";
    readonly cardsStats: "workboard.cards.stats";
    readonly cardsRuns: "workboard.cards.runs";
    readonly cardsSpecify: "workboard.cards.specify";
    readonly cardsDecompose: "workboard.cards.decompose";
    readonly cardsArchive: "workboard.cards.archive";
    readonly cardsExport: "workboard.cards.export";
    readonly boardsList: "workboard.boards.list";
    readonly boardsUpsert: "workboard.boards.upsert";
    readonly boardsArchive: "workboard.boards.archive";
    readonly boardsDelete: "workboard.boards.delete";
    readonly notificationsSubscribe: "workboard.notifications.subscribe";
    readonly notificationsList: "workboard.notifications.list";
    readonly notificationsDelete: "workboard.notifications.delete";
    readonly notificationsEvents: "workboard.notifications.events";
    readonly notificationsAdvance: "workboard.notifications.advance";
    readonly attachmentsList: "workboard.cards.attachments.list";
    readonly attachmentsGet: "workboard.cards.attachments.get";
    readonly attachmentsAdd: "workboard.cards.attachments.add";
    readonly attachmentsDelete: "workboard.cards.attachments.delete";
    readonly workerLog: "workboard.cards.workerLog";
    readonly protocolViolation: "workboard.cards.protocolViolation";
};

export declare const OPENCLAW_WORKBOARD_STATUSES: readonly [
    "triage",
    "backlog",
    "todo",
    "scheduled",
    "ready",
    "running",
    "review",
    "blocked",
    "done"
];

export declare class OpenClawAgentConfigApiClient extends GatewayAgentConfigApiClient {
    private readonly rpcClient;
    constructor(options: OpenClawAgentConfigApiClientOptions);
    listProfiles(): Promise<AgentProfileSummary[]>;
    getProfileConfig(_agentId: string): Promise<AgentConfig>;
    patchProfileConfig(_agentId: string, _diff: AgentConfigDraftDiff, _options?: PatchProfileConfigOptions): Promise<AgentConfig>;
}

export type OpenClawAgentConfigApiClientOptions = HttpApiClientOptions & {
    /** Shared OpenClaw socket for RPC dispatch (injected by createApiClient). */
    rpcClient?: OpenClawRpcTransport | null;
};

export declare class OpenClawApiClient extends GatewayApiClient {
    private readonly wsUrl?;
    private readonly rpcClientOverride;
    private readonly rpcClientOptions?;
    private rpcClient;
    constructor(options: OpenClawApiClientOptions);
    getCapabilities(): Promise<OpenClawCapabilities>;
    getRuntimeCapabilities(): Promise<RuntimeCapabilities>;
    startRun(body: GatewayRunStartBody): Promise<OpenClawRunStatus>;
    getRun(runId: string): Promise<OpenClawRunStatus>;
    stopRun(runId: string): Promise<{
        status: string;
    }>;
    resolveRunApproval<T = unknown>(): Promise<T>;
    private getRpcClient;
}

export type OpenClawApiClientOptions = HttpApiClientOptions & {
    wsUrl?: string;
    rpcClient?: OpenClawRpcTransport | null;
    rpcClientOptions?: OpenClawWebSocketClientOptions;
};

export type OpenClawCapabilities = GatewayCapabilities & {
    object?: "openclaw.api_server.capabilities" | string;
    platform?: "openclaw" | string;
    rpcMethods?: readonly string[];
};

/**
 * Anything that retains the gateway handshake — `GatewayRpcClient` (and the
 * OpenClaw WebSocket client extending it) satisfies this via `getHelloFrame`.
 */
export type OpenClawHelloSource = {
    getHelloFrame(): unknown;
    connect?(): Promise<void>;
};

export declare class OpenClawMediaApiClient extends GatewayMediaApiClient {
    private readonly wsUrl?;
    private readonly rpcClientOverride;
    private readonly rpcClientOptions?;
    private rpcClient;
    constructor(options: OpenClawMediaApiClientOptions);
    listMediaProviders(kind?: GatewayMediaKind | null): Promise<GatewayMediaProviderList>;
    generateAudio(body: GatewayMediaGenerateInput, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateTextToSpeech(body: GatewayTextToSpeechRequest, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateMedia(body: GatewayMediaGenerateRequest, idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateImage(_body: GatewayMediaGenerateInput, _idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateVideo(_body: GatewayMediaGenerateInput, _idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    generateMusic(_body: GatewayMediaGenerateInput, _idempotencyKey?: string): Promise<GatewayMediaGenerationResult>;
    getMediaJob(_kind: GatewayMediaKind, _jobId: string): Promise<GatewayMediaGenerationResult>;
    waitForMediaJob(_kind: GatewayMediaKind, _jobId: string, _options?: GatewayMediaJobWaitOptions): Promise<GatewayMediaGenerationResult>;
    listMediaAssets(_options?: GatewayMediaAssetListOptions): Promise<GatewayMediaAssetList>;
    getMediaAssetMetadata(_assetId: string): Promise<GatewayMediaAsset>;
    createMediaAsset(_body: GatewayMediaAssetUploadRequest, _idempotencyKey?: string): Promise<GatewayMediaAsset>;
    uploadMediaAsset(_body: GatewayMediaAssetUploadRequest, _idempotencyKey?: string): Promise<GatewayMediaAsset>;
    deleteMediaAsset(_assetId: string): Promise<GatewayMediaAssetDeleteResult>;
    getMediaAsset(_assetId: string, _init?: GatewayMediaAssetRequest): Promise<Blob>;
    getAudioAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getImageAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getVideoAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    getMusicAsset(assetId: string, init?: GatewayMediaAssetRequest): Promise<Blob>;
    private convertViaTts;
    private getRpcClient;
}

export type OpenClawMediaApiClientOptions = HttpApiClientOptions & {
    /** Optional shared RPC transport (e.g. from an existing `OpenClawApiClient`). */
    rpcClient?: OpenClawRpcTransport | null;
    /** Explicit WebSocket URL when not derivable from `baseUrl`. */
    wsUrl?: string;
    rpcClientOptions?: OpenClawWebSocketClientOptions;
};

export type OpenClawRpcTransport = {
    request<TPayload>(method: string, params?: Record<string, unknown>): Promise<TPayload>;
};

export type OpenClawRunStatus = GatewayRunStatus & {
    object?: "openclaw.run" | string;
};

export type OpenClawRuntimeControlClientOptions = RuntimeControlClientOptions & {
    rpc?: OpenClawRpc;
    takeRpcOwnership?: boolean;
};

export declare class OpenClawSseRunEventProvider extends GatewaySseRunEventProvider {
    constructor(options: OpenClawSseRunEventProviderOptions);
    subscribe(_params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
}

export type OpenClawSseRunEventProviderOptions = GatewaySseRunEventProviderOptions;

export declare class OpenClawWebSocketClient extends GatewayWebSocketClient implements OpenClawRpc {
    constructor(wsUrl: string, authToken: string | null, options?: OpenClawWebSocketClientOptions);
    request<TPayload>(method: string, params?: Record<string, unknown>, options?: {
        signal?: AbortSignal;
    }): Promise<TPayload>;
    subscribe(listener: (event: OpenClawRpcEvent) => void): () => void;
    onConnectionState(listener: (state: RawGatewayConnectionState, error?: unknown) => void): () => void;
    dispose(): Promise<void>;
}

export type OpenClawWebSocketClientOptions = GatewayWebSocketClientOptions;

export declare class OpenClawWikiApiClient extends GatewayWikiApiClient {
    constructor(options: HttpApiClientOptions);
    listWikiVaults(): Promise<GatewayWikiVaultList>;
    getWikiVault(_vaultId: string): Promise<GatewayWikiVault>;
    getWikiTree(_vaultId: string): Promise<GatewayWikiTree>;
    readWikiPage(_vaultId: string, _path: string): Promise<GatewayWikiPage>;
    ingestWiki(_vaultId: string, _body: GatewayWikiIngestRequest, _idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    compileWiki(_vaultId: string, _body: GatewayWikiCompileRequest, _idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    promoteWiki(_vaultId: string, _body: GatewayWikiPromoteRequest, _idempotencyKey?: string): Promise<GatewayWikiJobResult>;
    getWikiJob(_vaultId: string, _jobId: string): Promise<GatewayWikiJobResult>;
    getWikiArtifact(_vaultId: string, _artifactId: string, _init?: GatewayWikiArtifactRequest): Promise<Blob>;
}

export type OpenClawWorkboardCard = {
    id: string;
    title: string;
    notes?: string;
    status: OpenClawWorkboardStatus;
    priority: OpenClawWorkboardPriority;
    labels: string[];
    agentId?: string;
    boardId?: string;
    sessionKey?: string;
    runId?: string;
    taskId?: string;
    position: number;
    createdAt: number;
    updatedAt: number;
    metadata?: Record<string, unknown>;
};

export type OpenClawWorkboardPriority = (typeof OPENCLAW_WORKBOARD_PRIORITIES)[number];

export type OpenClawWorkboardRpc = {
    request<TPayload>(method: string, params?: Record<string, unknown>): Promise<TPayload>;
    listCards(params?: {
        boardId?: string;
    }): Promise<{
        cards: OpenClawWorkboardCard[];
        statuses?: readonly OpenClawWorkboardStatus[];
    }>;
    createCard(params: Record<string, unknown>): Promise<{
        card: OpenClawWorkboardCard;
    }>;
    updateCard(id: string, patch: Record<string, unknown>): Promise<{
        card: OpenClawWorkboardCard;
    }>;
    moveCard(id: string, status: OpenClawWorkboardStatus, position?: number): Promise<{
        card: OpenClawWorkboardCard;
    }>;
    dispatch(params?: Record<string, unknown>): Promise<Record<string, unknown>>;
};

export type OpenClawWorkboardStatus = (typeof OPENCLAW_WORKBOARD_STATUSES)[number];

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 transformOpenClawHello(payload: unknown, options?: TransformOpenClawHelloOptions): ResolvedProviderCapabilities;

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