orchestrator-client 5.7.0 → 5.7.2

package/dist/index.d.ts

@@ -57,6 +57,10 @@ interface TaskCreateResponse {
 interface TaskCancelResponse {
     taskId: string;
     killed: boolean;
+    via: "local" | "remote" | "none" | "fallback";
+    holderId?: string;
+    reason?: string;
+    message: string;
 }
 interface VSATaskCreateResponse extends TaskCreateResponse {
 }
@@ -170,6 +174,10 @@ interface ErrorCountResult {
 interface ErrorPurgeResult {
     deleted: number;
 }
+interface ErrorEventListResult {
+    items: ErrorEventDetail[];
+    pagination: Pagination$1;
+}
 
 interface HealthStatus {
     status: string;
@@ -317,10 +325,30 @@ interface ConfigurationStatus {
     orchestratorModel: string | null;
     summaryModel: string | null;
     translateModel: string | null;
+    llmBackendsCount: number;
+    mcpServersCount: number;
+    totalTasks: number;
+    queuedTasks: number;
+    activeTasks: number;
+    pendingApprovalTasks: number;
+    subagentsEnabled: boolean;
     localizationTargets: Record<string, string>[];
-    llmbackends: LLMBackendInfo[];
-    mcpservers: MCPServerInfo[];
-    builtinTools: string[];
+}
+interface SubagentsStatus {
+    subagentsEnabled: boolean;
+}
+interface ReloadServicesResult {
+    timestamp: string;
+    llmBackends: Record<string, unknown>;
+    mcpServers: Record<string, unknown>;
+    slotManager: Record<string, unknown>;
+    nextScheduledReload?: string;
+}
+interface ReloadStatus {
+    enabled: boolean;
+    intervalHours: number | null;
+    lastReload?: string;
+    nextScheduledReload?: string;
 }
 
 interface ToolInfo {
@@ -333,6 +361,35 @@ interface ToolsListResult {
     totalTools: number;
     servers: string[];
 }
+interface ToolCatalogEntry {
+    name: string;
+    description: string;
+    provenanceKind: string;
+    provenanceServer?: string;
+    category: string;
+    tags: string[];
+    workflowIds?: string[];
+    dangerous: boolean;
+    hasFragment: boolean;
+}
+interface ToolCatalogResult {
+    tools: ToolCatalogEntry[];
+    totalTools: number;
+    providers: string[];
+}
+interface MCPRefreshResult {
+    results: Record<string, unknown>;
+    totalRefreshed: number;
+}
+interface CatalogValidationIssue {
+    toolName: string;
+    issueType: string;
+    detail: string;
+}
+interface CatalogValidationResult {
+    issues: CatalogValidationIssue[];
+    totalIssues: number;
+}
 
 interface CompactionEvent {
     id: number;
@@ -375,12 +432,13 @@ interface AuthConfig {
 }
 interface WebSocketClientInfo {
     clientId: string;
-    subscription: Record<string, unknown>;
-    connected: boolean;
+    connectedAt: string;
 }
 interface WebSocketStatus {
     connectedClients: number;
     clients: WebSocketClientInfo[];
+    eventListenerHealthy: boolean;
+    lastEventTime?: string;
 }
 
 interface SuccessResponse {
@@ -388,11 +446,34 @@ interface SuccessResponse {
 }
 interface MioContext {
     taskId: string;
+    modelId: string;
     currentTokens: number;
     contextLimit: number;
     usagePercentage: number;
-    archivedCount: number;
-    activeCount: number;
+    totalMessages: number;
+    activeMessages: number;
+    archivedMessages: number;
+    messagesWithoutTokenCount: number;
+}
+interface MioMemoryItem {
+    id: string;
+    taskId: string | null;
+    title: string;
+    content: string;
+    tags: string[];
+    linkedTaskId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface MioMemoriesResult {
+    memories: MioMemoryItem[];
+    total: number;
+}
+interface MessageDeleteMultipleResult {
+    deletedIds: number[];
+    failedIds: number[];
+    totalDeleted: number;
+    totalFailed: number;
 }
 interface WorkflowStates {
     validStates: Record<string, string[]>;
@@ -430,6 +511,15 @@ interface OrchestratorClientOptions {
     timeoutMs?: number;
     /** Max retry attempts on transient failures (default: 3). */
     maxRetries?: number;
+    /**
+     * Locale tag sent as `X-Locale` on every request (e.g. `"hu-hu"`, `"en-us"`).
+     *
+     * When set the API returns translated content where available.
+     * When not set the API returns its default (English) content.
+     * Per-call locale overrides (on `listTasks`, `getTaskStatus`, etc.)
+     * take precedence over this global setting.
+     */
+    locale?: string;
     /**
      * Custom fetch implementation override.
      *
@@ -457,6 +547,7 @@ declare class OrchestratorAsync {
     protected _getToken: (() => string | Promise<string>) | undefined;
     protected _timeoutMs: number;
     protected _maxRetries: number;
+    protected _locale: string | undefined;
     protected _fetch: typeof globalThis.fetch;
     protected _abortController: AbortController | null;
     constructor(opts?: OrchestratorClientOptions);
@@ -476,57 +567,75 @@ declare class OrchestratorAsync {
     protected _put<T>(path: string, body?: unknown): Promise<T>;
     protected _delete<T>(path: string): Promise<T>;
     listTasks(params?: {
-        workflowId?: string;
-        status?: string;
+        page?: number;
         limit?: number;
-        offset?: number;
-        sortBy?: string;
-        sortOrder?: string;
+        orderBy?: string;
+        orderDirection?: string;
+        workflowId?: string;
+        locale?: string;
     }): Promise<TaskListResult>;
     createTask(params: {
         workflowId: string;
         goalPrompt: string;
         maxIterations?: number;
-        options?: Record<string, boolean>;
+        reasoningEffort?: string;
+        systemPrompt?: string;
+        developerPrompt?: string;
         ticketId?: string;
-        title?: string;
-        modelId?: string;
+        ticketText?: string;
+        summary?: string;
+        problemSummary?: string;
+        solutionStrategy?: string;
+        agentModelId?: string;
+        orchestratorModelId?: string;
+        availableTools?: string[];
+        attachmentIds?: string[];
+        options?: Record<string, boolean>;
     }): Promise<TaskCreateResponse>;
-    getTaskStatus(taskId: string): Promise<TaskDetail>;
-    getTaskConversation(taskId: string): Promise<ConversationResult>;
+    getTaskStatus(taskId: string, locale?: string): Promise<TaskDetail>;
+    setTaskStatus(taskId: string, status: string): Promise<SuccessResponse>;
+    getTaskConversation(taskId: string, params?: {
+        includeSummaries?: boolean;
+        excludeArchived?: boolean;
+        locale?: string;
+    }): Promise<ConversationResult>;
     getArchivedMessageContent(taskId: string, messageId: number): Promise<Record<string, unknown>>;
     getTaskCompactions(taskId: string): Promise<CompactionEvent[]>;
     getTaskJournal(taskId: string): Promise<TaskJournal>;
-    cancelTask(taskId: string): Promise<SuccessResponse>;
+    cancelTask(taskId: string): Promise<TaskCancelResponse>;
     deleteTask(taskId: string): Promise<TaskDeleteResult>;
     deleteTasks(taskIds: string[]): Promise<TaskDeleteResult>;
-    uploadAttachment(taskId: string, file: File | Blob, filename?: string): Promise<AttachmentUploadResponse>;
-    downloadAttachment(taskId: string, attachmentId: string): Promise<Blob>;
-    sendInteractiveMessage(taskId: string, content: string): Promise<SuccessResponse>;
+    uploadAttachment(file: File | Blob, filename?: string): Promise<AttachmentUploadResponse>;
+    downloadAttachment(attachmentId: string): Promise<Blob>;
+    sendInteractiveMessage(taskId: string, message: string, attachmentIds?: string[]): Promise<SuccessResponse>;
     markInteractiveComplete(taskId: string): Promise<SuccessResponse>;
     markInteractiveFailed(taskId: string): Promise<SuccessResponse>;
-    approveInteractiveAction(taskId: string): Promise<SuccessResponse>;
-    sendProactiveGuide(taskId: string, guide: string): Promise<SuccessResponse>;
+    approveInteractiveAction(taskId: string, approved?: boolean): Promise<SuccessResponse>;
+    stopInteractive(taskId: string): Promise<SuccessResponse>;
+    sendProactiveGuide(taskId: string, message: string, attachmentIds?: string[]): Promise<SuccessResponse>;
     respondProactiveHelp(taskId: string, response: string): Promise<SuccessResponse>;
-    approveProactiveAction(taskId: string): Promise<SuccessResponse>;
-    sendTicketGuide(taskId: string, guide: string): Promise<SuccessResponse>;
+    approveProactiveAction(taskId: string, approved?: boolean): Promise<SuccessResponse>;
+    sendTicketGuide(taskId: string, message: string, attachmentIds?: string[]): Promise<SuccessResponse>;
     respondTicketHelp(taskId: string, response: string): Promise<SuccessResponse>;
-    approveTicketAction(taskId: string): Promise<SuccessResponse>;
+    approveTicketAction(taskId: string, approved?: boolean): Promise<SuccessResponse>;
     wakeTicket(taskId: string): Promise<SuccessResponse>;
-    sendMatrixMessage(taskId: string, content: string): Promise<SuccessResponse>;
+    sendMatrixMessage(taskId: string, message: string, attachmentIds?: string[]): Promise<SuccessResponse>;
     markMatrixComplete(taskId: string): Promise<SuccessResponse>;
     markMatrixFailed(taskId: string): Promise<SuccessResponse>;
-    approveMatrixAction(taskId: string): Promise<SuccessResponse>;
-    getMatrixConversation(taskId: string): Promise<MatrixConversationResult>;
+    approveMatrixAction(taskId: string, approved?: boolean): Promise<SuccessResponse>;
+    getMatrixConversation(taskId: string, phase?: number, includeSummaries?: boolean): Promise<MatrixConversationResult>;
     createVSATask(params: {
+        userId: string;
         goalPrompt: string;
         title?: string;
-        modelId?: string;
-        /** Short-lived AiDIT delegated token (RFC 8693). Stored encrypted;
-         *  transparently appended as `token` to mcp-aidit tool-call arguments. */
+        agentModelId?: string;
+        orchestratorModelId?: string;
+        attachmentIds?: string[];
+        options?: Record<string, boolean>;
         delegatedToken?: string;
     }): Promise<VSATaskCreateResponse>;
-    sendVSAMessage(taskId: string, content: string, options?: {
+    sendVSAMessage(taskId: string, message: string, options?: {
+        attachmentIds?: string[];
         /** Short-lived AiDIT delegated token. When provided, overwrites the
          *  token stored for the task. Omitting leaves the existing token unchanged. */
         delegatedToken?: string;
@@ -537,46 +646,58 @@ declare class OrchestratorAsync {
     markVSAFailed(taskId: string): Promise<SuccessResponse>;
     stopVSA(taskId: string): Promise<SuccessResponse>;
     deleteVSA(taskId: string): Promise<SuccessResponse>;
-    listVSATasks(params?: {
-        status?: string;
+    listVSATasks(userId: string, params?: {
         limit?: number;
         offset?: number;
     }): Promise<TaskListResult>;
-    searchVSATasks(query: string): Promise<TaskListResult>;
-    deleteVSATasksBulk(taskIds: string[]): Promise<SuccessResponse>;
-    sendMioMessage(taskId: string, content: string): Promise<SuccessResponse>;
-    approveMioAction(taskId: string): Promise<SuccessResponse>;
+    searchVSATasks(userId: string, query: string, limit?: number): Promise<TaskListResult>;
+    deleteVSATasksBulk(taskIds: string[]): Promise<TaskDeleteResult>;
+    sendMioMessage(taskId: string, message: string, attachmentIds?: string[]): Promise<SuccessResponse>;
+    approveMioAction(taskId: string, approved?: boolean, feedback?: string): Promise<SuccessResponse>;
     wakeMio(taskId: string): Promise<SuccessResponse>;
     sendMioUserAway(taskId: string): Promise<SuccessResponse>;
     markMioComplete(taskId: string): Promise<SuccessResponse>;
     markMioFailed(taskId: string): Promise<SuccessResponse>;
     archiveMio(taskId: string): Promise<SuccessResponse>;
     getMioContext(taskId: string): Promise<MioContext>;
+    getMioMemories(taskId: string, includeCommon?: boolean): Promise<MioMemoriesResult>;
     listTools(): Promise<ToolsListResult>;
+    getToolCatalog(): Promise<ToolCatalogResult>;
+    refreshMCPTools(): Promise<MCPRefreshResult>;
+    validateToolCatalog(): Promise<CatalogValidationResult>;
     getWorkflowStates(): Promise<WorkflowStates>;
     updateTaskModels(taskId: string, models: {
-        agent?: string;
-        orchestrator?: string;
+        agentModelId?: string;
+        orchestratorModelId?: string;
     }): Promise<SuccessResponse>;
-    updateTaskIteration(taskId: string, iteration: number): Promise<SuccessResponse>;
+    updateTaskIteration(taskId: string, iteration?: number, maxIterations?: number): Promise<SuccessResponse>;
     updateTaskWorkflowData(taskId: string, workflowData: Record<string, unknown>): Promise<SuccessResponse>;
     deleteMessage(taskId: string, messageId: number): Promise<SuccessResponse>;
-    deleteMessages(taskId: string, messageIds: number[]): Promise<SuccessResponse>;
+    deleteMessages(taskId: string, messageIds: number[]): Promise<MessageDeleteMultipleResult>;
     updateMessage(taskId: string, messageId: number, update: {
         content?: string;
         reasoning?: string;
     }): Promise<SuccessResponse>;
     resetMatrixToPhase(taskId: string, phase: number): Promise<SuccessResponse>;
-    getMessageTranslations(taskId: string, messageId: number, locale?: string): Promise<MessageTranslationsResult>;
+    getMessageTranslations(taskId: string, messageId: number): Promise<MessageTranslationsResult>;
     listErrors(params?: {
-        since?: string;
-        severity?: string;
-        source?: string;
+        page?: number;
         limit?: number;
-        offset?: number;
-    }): Promise<ErrorEventDetail[]>;
+        taskId?: string;
+        severity?: string[];
+        source?: string[];
+        workflowId?: string;
+        errorCode?: string;
+        exceptionType?: string;
+        holderId?: string;
+        requestId?: string;
+        search?: string;
+        since?: string;
+        until?: string;
+        orderDirection?: string;
+    }): Promise<ErrorEventListResult>;
     getErrorDetail(errorId: string): Promise<ErrorEventDetail>;
-    getErrorStats(since?: string): Promise<ErrorStatsResult>;
+    getErrorStats(since?: string, topN?: number): Promise<ErrorStatsResult>;
     countErrors(since?: string): Promise<ErrorCountResult>;
     purgeErrors(): Promise<ErrorPurgeResult>;
     health(): Promise<HealthStatus>;
@@ -603,6 +724,10 @@ declare class OrchestratorAsync {
     setTranslateModel(modelName: string): Promise<SuccessResponse>;
     getTokenWorkerStatus(): Promise<TokenWorkerStatus>;
     getSlotsStatus(): Promise<SlotsStatus>;
+    getSubagentsStatus(): Promise<SubagentsStatus>;
+    setSubagentsEnabled(enabled: boolean): Promise<SuccessResponse>;
+    reloadServices(): Promise<ReloadServicesResult>;
+    getReloadStatus(): Promise<ReloadStatus>;
     getAuthConfig(): Promise<AuthConfig>;
     getWebSocketStatus(): Promise<WebSocketStatus>;
     streamTaskStatus(taskId: string): AsyncGenerator<Record<string, unknown>>;
@@ -621,34 +746,37 @@ declare class Orchestrator {
     close(): void;
     listTasks(params?: Parameters<OrchestratorAsync["listTasks"]>[0]): TaskListResult;
     createTask(params: Parameters<OrchestratorAsync["createTask"]>[0]): TaskCreateResponse;
-    getTaskStatus(taskId: string): TaskDetail;
-    getTaskConversation(taskId: string): ConversationResult;
+    getTaskStatus(taskId: string, locale?: string): TaskDetail;
+    setTaskStatus(taskId: string, status: string): SuccessResponse;
+    getTaskConversation(taskId: string, params?: Parameters<OrchestratorAsync["getTaskConversation"]>[1]): ConversationResult;
     getArchivedMessageContent(taskId: string, messageId: number): Record<string, unknown>;
     getTaskCompactions(taskId: string): CompactionEvent[];
     getTaskJournal(taskId: string): TaskJournal;
-    cancelTask(taskId: string): SuccessResponse;
+    cancelTask(taskId: string): TaskCancelResponse;
     deleteTask(taskId: string): TaskDeleteResult;
     deleteTasks(taskIds: string[]): TaskDeleteResult;
-    uploadAttachment(taskId: string, file: File | Blob, filename?: string): AttachmentUploadResponse;
-    downloadAttachment(taskId: string, attachmentId: string): Blob;
-    sendInteractiveMessage(taskId: string, content: string): SuccessResponse;
+    uploadAttachment(file: File | Blob, filename?: string): AttachmentUploadResponse;
+    downloadAttachment(attachmentId: string): Blob;
+    sendInteractiveMessage(taskId: string, message: string, attachmentIds?: string[]): SuccessResponse;
     markInteractiveComplete(taskId: string): SuccessResponse;
     markInteractiveFailed(taskId: string): SuccessResponse;
-    approveInteractiveAction(taskId: string): SuccessResponse;
-    sendProactiveGuide(taskId: string, guide: string): SuccessResponse;
+    approveInteractiveAction(taskId: string, approved?: boolean): SuccessResponse;
+    stopInteractive(taskId: string): SuccessResponse;
+    sendProactiveGuide(taskId: string, message: string, attachmentIds?: string[]): SuccessResponse;
     respondProactiveHelp(taskId: string, response: string): SuccessResponse;
-    approveProactiveAction(taskId: string): SuccessResponse;
-    sendTicketGuide(taskId: string, guide: string): SuccessResponse;
+    approveProactiveAction(taskId: string, approved?: boolean): SuccessResponse;
+    sendTicketGuide(taskId: string, message: string, attachmentIds?: string[]): SuccessResponse;
     respondTicketHelp(taskId: string, response: string): SuccessResponse;
-    approveTicketAction(taskId: string): SuccessResponse;
+    approveTicketAction(taskId: string, approved?: boolean): SuccessResponse;
     wakeTicket(taskId: string): SuccessResponse;
-    sendMatrixMessage(taskId: string, content: string): SuccessResponse;
+    sendMatrixMessage(taskId: string, message: string, attachmentIds?: string[]): SuccessResponse;
     markMatrixComplete(taskId: string): SuccessResponse;
     markMatrixFailed(taskId: string): SuccessResponse;
-    approveMatrixAction(taskId: string): SuccessResponse;
-    getMatrixConversation(taskId: string): MatrixConversationResult;
+    approveMatrixAction(taskId: string, approved?: boolean): SuccessResponse;
+    getMatrixConversation(taskId: string, phase?: number, includeSummaries?: boolean): MatrixConversationResult;
     createVSATask(params: Parameters<OrchestratorAsync["createVSATask"]>[0]): VSATaskCreateResponse;
-    sendVSAMessage(taskId: string, content: string, options?: {
+    sendVSAMessage(taskId: string, message: string, options?: {
+        attachmentIds?: string[];
         delegatedToken?: string;
     }): SuccessResponse;
     renameVSATask(taskId: string, title: string): SuccessResponse;
@@ -657,34 +785,38 @@ declare class Orchestrator {
     markVSAFailed(taskId: string): SuccessResponse;
     stopVSA(taskId: string): SuccessResponse;
     deleteVSA(taskId: string): SuccessResponse;
-    listVSATasks(params?: Parameters<OrchestratorAsync["listVSATasks"]>[0]): TaskListResult;
-    searchVSATasks(query: string): TaskListResult;
-    deleteVSATasksBulk(taskIds: string[]): SuccessResponse;
-    sendMioMessage(taskId: string, content: string): SuccessResponse;
-    approveMioAction(taskId: string): SuccessResponse;
+    listVSATasks(userId: string, params?: Parameters<OrchestratorAsync["listVSATasks"]>[1]): TaskListResult;
+    searchVSATasks(userId: string, query: string, limit?: number): TaskListResult;
+    deleteVSATasksBulk(taskIds: string[]): TaskDeleteResult;
+    sendMioMessage(taskId: string, message: string, attachmentIds?: string[]): SuccessResponse;
+    approveMioAction(taskId: string, approved?: boolean, feedback?: string): SuccessResponse;
     wakeMio(taskId: string): SuccessResponse;
     sendMioUserAway(taskId: string): SuccessResponse;
     markMioComplete(taskId: string): SuccessResponse;
     markMioFailed(taskId: string): SuccessResponse;
     archiveMio(taskId: string): SuccessResponse;
     getMioContext(taskId: string): MioContext;
+    getMioMemories(taskId: string, includeCommon?: boolean): MioMemoriesResult;
     listTools(): ToolsListResult;
+    getToolCatalog(): ToolCatalogResult;
+    refreshMCPTools(): MCPRefreshResult;
+    validateToolCatalog(): CatalogValidationResult;
     getWorkflowStates(): WorkflowStates;
     updateTaskModels(taskId: string, models: {
-        agent?: string;
-        orchestrator?: string;
+        agentModelId?: string;
+        orchestratorModelId?: string;
     }): SuccessResponse;
-    updateTaskIteration(taskId: string, iteration: number): SuccessResponse;
+    updateTaskIteration(taskId: string, iteration?: number, maxIterations?: number): SuccessResponse;
     updateTaskWorkflowData(taskId: string, workflowData: Record<string, unknown>): SuccessResponse;
     deleteMessage(taskId: string, messageId: number): SuccessResponse;
-    deleteMessages(taskId: string, messageIds: number[]): SuccessResponse;
+    deleteMessages(taskId: string, messageIds: number[]): MessageDeleteMultipleResult;
     updateMessage(taskId: string, messageId: number, update: {
         content?: string;
         reasoning?: string;
     }): SuccessResponse;
     resetMatrixToPhase(taskId: string, phase: number): SuccessResponse;
-    getMessageTranslations(taskId: string, messageId: number, locale?: string): MessageTranslationsResult;
-    listErrors(params?: Parameters<OrchestratorAsync["listErrors"]>[0]): ErrorEventDetail[];
+    getMessageTranslations(taskId: string, messageId: number): MessageTranslationsResult;
+    listErrors(params?: Parameters<OrchestratorAsync["listErrors"]>[0]): ErrorEventListResult;
     getErrorDetail(errorId: string): ErrorEventDetail;
     getErrorStats(since?: string): ErrorStatsResult;
     countErrors(since?: string): ErrorCountResult;
@@ -713,6 +845,10 @@ declare class Orchestrator {
     setTranslateModel(modelName: string): SuccessResponse;
     getTokenWorkerStatus(): TokenWorkerStatus;
     getSlotsStatus(): SlotsStatus;
+    getSubagentsStatus(): SubagentsStatus;
+    setSubagentsEnabled(enabled: boolean): SuccessResponse;
+    reloadServices(): ReloadServicesResult;
+    getReloadStatus(): ReloadStatus;
     getAuthConfig(): AuthConfig;
     getWebSocketStatus(): WebSocketStatus;
     streamTaskStatus(_taskId: string): Record<string, unknown>[];
@@ -800,31 +936,147 @@ interface RealtimeClientOptions {
     getToken?: (() => string | Promise<string>) | string;
     /** Whether to auto-connect on construction (default: false). */
     autoConnect?: boolean;
+    /**
+     * Client identifier sent as the `client_id` query parameter at connection
+     * time.  The server uses this for logging/diagnostics.
+     * Defaults to `"orchestrator-client"`.
+     */
+    clientId?: string;
+    /**
+     * Locale tag sent as the `locale` query parameter at connection time
+     * (e.g. `"hu-hu"`, `"en-us"`).  When set the server automatically joins
+     * the client into the matching `locale:<tag>` room so translation-ready
+     * events are delivered without a separate `subscribeLocale()` call.
+     */
+    locale?: string;
 }
 /**
  * Socket.IO-based realtime client for receiving orchestrator events.
+ *
+ * The server wraps all domain events in a `message` Socket.IO event with an
+ * inner `event_type` field. This client unwraps the envelope and dispatches
+ * to registered handlers by event_type.
+ *
+ * ## Two subscription APIs — choose one or mix them:
+ *
+ * ### 1. Event-type handlers via `on(event, handler)`
+ * Registers a callback for a specific event type string (e.g.
+ * `"task_status_changed"`). You still need to join the relevant rooms
+ * manually via `subscribeTask()`, `subscribeEvents()`, etc.
+ *
+ * ### 2. Room-scoped subscribers via `subscribe(handler, rooms)`
+ * Mirrors the WebSocketProvider pattern used in the webui. Each call
+ * returns an opaque subscription id. Calling `unsubscribe(id)` removes it.
+ * Room membership is kept in sync automatically: the client joins the union
+ * of all subscribers' rooms and leaves rooms that are no longer needed.
+ * The handler receives the unwrapped event dict for every event from those
+ * rooms, regardless of type.
  */
 declare class RealtimeClient {
     private _baseUrl;
     private _socketOptions;
     private _getToken?;
+    private _clientId;
+    private _locale?;
     private _socket;
     private _handlers;
     private _connected;
+    private _subscriptions;
+    private _currentRooms;
+    private _subIdCounter;
     constructor(baseUrl: string, opts: RealtimeClientOptions);
     get connected(): boolean;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    /**
+     * Dispatch a message envelope to registered handlers and subscribers.
+     * The server sends: socket.emit("message", {type: "message", event: {..., event_type: "...", ...}})
+     */
+    private _dispatch;
     /**
      * Subscribe to realtime events for a specific task.
+     * Emits a `join` event with `{rooms: ["task:{taskId}"]}`.
      */
-    subscribeTask(taskId: string): Promise<void>;
+    subscribeTask(taskId: string): void;
     /**
      * Unsubscribe from realtime events for a specific task.
+     * Emits a `leave` event with `{rooms: ["task:{taskId}"]}`.
+     */
+    unsubscribeTask(taskId: string): void;
+    /**
+     * Subscribe to event-type-scoped rooms.
+     * e.g. subscribeEvents("task_created", "task_deleted")
+     */
+    subscribeEvents(...eventTypes: string[]): void;
+    /**
+     * Unsubscribe from event-type-scoped rooms.
+     */
+    unsubscribeEvents(...eventTypes: string[]): void;
+    /**
+     * Subscribe to the `all` broadcast room (receives all events).
+     */
+    subscribeAll(): void;
+    /**
+     * Subscribe to a locale-specific room.
+     */
+    subscribeLocale(locale: string): void;
+    /**
+     * Unsubscribe from a locale-specific room.
      */
-    unsubscribeTask(taskId: string): Promise<void>;
+    unsubscribeLocale(locale: string): void;
+    /**
+     * Join arbitrary rooms by name.
+     */
+    joinRooms(rooms: string[]): void;
+    /**
+     * Leave arbitrary rooms by name.
+     */
+    leaveRooms(rooms: string[]): void;
+    /**
+     * Register a subscriber that receives all events from the given rooms.
+     *
+     * Room membership is managed automatically: the client joins the union
+     * of all active subscribers' rooms and leaves rooms that are no longer
+     * needed when the last subscriber referencing them is removed.
+     *
+     * The `handler` receives the unwrapped event dict (same object that
+     * `on()` handlers receive).
+     *
+     * Returns an opaque subscription id that must be passed to
+     * `unsubscribe()` to remove the subscription.
+     *
+     * Example — mirror the webui's per-component subscription pattern:
+     *
+     *   const id = rt.subscribe((event) => {
+     *     if (event.event_type === "task_status_changed") { ... }
+     *   }, [`task:${taskId}`]);
+     *
+     *   // later, on cleanup:
+     *   rt.unsubscribe(id);
+     */
+    subscribe(handler: EventHandler, rooms: string[]): string;
+    /**
+     * Remove a subscription registered via `subscribe()`.
+     *
+     * Rooms that are no longer referenced by any remaining subscriber are
+     * left automatically.
+     */
+    unsubscribe(id: string): void;
+    /**
+     * Diff the union of all subscribers' rooms against the currently joined
+     * rooms and emit `join`/`leave` for the delta.  No-ops when not connected.
+     */
+    private _syncRooms;
+    /**
+     * Send a ping to the server.
+     */
+    ping(): void;
     /**
      * Register a handler for a specific event type.
+     *
+     * Domain events (task_created, task_status_changed, etc.) are dispatched
+     * via the message envelope. Raw socket events (connect, disconnect,
+     * connection_established, rooms_updated, pong) are wired directly.
      */
     on(event: string, handler: EventHandler): void;
     /**