doover-js 0.5.3 → 0.6.0

package/dist/gateway/gateway-client.d.ts

@@ -2,7 +2,16 @@ import type { DooverAuth } from "../auth/doover-auth";
 import type { DooverStatsCollector } from "../client/stats";
 import type { DooverClientConfig } from "../http/rest-client";
 import type { GatewayListenerMap, WebSocketSession } from "./types";
-import type { ChannelRef, JSONValue } from "../types/common";
+import type { Aggregate, ChannelRef, JSONValue, MessageStructure } from "../types/common";
+export type GatewayProvenanceHook = <T>(value: T, ctx: {
+    event: string;
+    sessionId?: string;
+}) => any;
+export interface ChannelHandlers {
+    onMessage?: (msg: MessageStructure) => void;
+    onMessageUpdate?: (msg: MessageStructure, requestData?: JSONValue) => void;
+    onAggregate?: (agg: Aggregate) => void;
+}
 export declare class GatewayClient {
     private readonly config;
     private socket;
@@ -15,11 +24,18 @@ export declare class GatewayClient {
     private opening;
     private listeners;
     private subscriptions;
+    private channelRegistry;
     private readonly auth;
     private stats;
+    private provenanceHook;
     constructor(config: DooverClientConfig, auth?: DooverAuth);
     /** Attach a stats collector. Call with `null` to detach. */
     setStats(stats: DooverStatsCollector | null): void;
+    /** Optional hook that stamps `__source` provenance onto emitted gateway
+     *  payloads. `DooverClient` / `LocalAgentClient` set this; standalone
+     *  `GatewayClient` users leave it null and get raw payloads. */
+    setProvenanceHook(hook: GatewayProvenanceHook | null): void;
+    private stamp;
     connect(): Promise<void>;
     private openSocket;
     disconnect(code?: number, reason?: string): void;
@@ -29,6 +45,12 @@ export declare class GatewayClient {
         diff_only?: boolean;
     }): void;
     unsubscribe(channel: ChannelRef): void;
+    /**
+     * Attach channel-scoped handlers. Returns an idempotent unsubscribe fn.
+     * The first handler for a channel triggers a wire-level subscribe; the
+     * last detach triggers a wire-level unsubscribe.
+     */
+    subscribeToChannel(channel: ChannelRef, handlers: ChannelHandlers): () => void;
     syncChannel(channel: ChannelRef): void;
     sendOneShotMessage(channel: ChannelRef, data: JSONValue): void;
     getSession(): WebSocketSession | null;

package/dist/gateway/gateway-client.js

@@ -32,7 +32,9 @@ class GatewayClient {
             close: new Set(),
         };
         this.subscriptions = new Map();
+        this.channelRegistry = new Map();
         this.stats = null;
+        this.provenanceHook = null;
         this.handleVisibilityChange = () => {
             if (typeof document === "undefined")
                 return;
@@ -50,6 +52,20 @@ class GatewayClient {
     setStats(stats) {
         this.stats = stats;
     }
+    /** Optional hook that stamps `__source` provenance onto emitted gateway
+     *  payloads. `DooverClient` / `LocalAgentClient` set this; standalone
+     *  `GatewayClient` users leave it null and get raw payloads. */
+    setProvenanceHook(hook) {
+        this.provenanceHook = hook;
+    }
+    stamp(value, event) {
+        if (!this.provenanceHook)
+            return value;
+        return this.provenanceHook(value, {
+            event,
+            ...(this.session?.session_id ? { sessionId: this.session.session_id } : {}),
+        });
+    }
     async connect() {
         this.explicitlyDisconnected = false;
         if (this.socket && this.socket.readyState <= WebSocket.OPEN) {
@@ -151,6 +167,59 @@ class GatewayClient {
             },
         });
     }
+    /**
+     * Attach channel-scoped handlers. Returns an idempotent unsubscribe fn.
+     * The first handler for a channel triggers a wire-level subscribe; the
+     * last detach triggers a wire-level unsubscribe.
+     */
+    subscribeToChannel(channel, handlers) {
+        const key = this.channelKey(channel);
+        let entry = this.channelRegistry.get(key);
+        if (!entry) {
+            entry = { handlers: new Set(), cleanup: [] };
+            this.channelRegistry.set(key, entry);
+            const matches = (c) => c.agent_id === channel.agent_id && c.name === channel.name;
+            const onMsgCreate = (msg) => {
+                if (!matches(msg.channel))
+                    return;
+                entry.handlers.forEach((h) => h.onMessage?.(msg));
+            };
+            const onMsgUpdate = (msg, requestData) => {
+                if (!matches(msg.channel))
+                    return;
+                entry.handlers.forEach((h) => h.onMessageUpdate?.(msg, requestData));
+            };
+            const onAggregate = (event) => {
+                if (!matches(event.channel))
+                    return;
+                entry.handlers.forEach((h) => h.onAggregate?.(event.aggregate));
+            };
+            const onChannelSync = (event) => {
+                if (!matches(event.channel))
+                    return;
+                entry.handlers.forEach((h) => h.onAggregate?.(event.aggregate));
+            };
+            this.on("messageCreate", onMsgCreate);
+            this.on("messageUpdate", onMsgUpdate);
+            this.on("aggregateUpdate", onAggregate);
+            this.on("channelSync", onChannelSync);
+            entry.cleanup.push(() => this.off("messageCreate", onMsgCreate), () => this.off("messageUpdate", onMsgUpdate), () => this.off("aggregateUpdate", onAggregate), () => this.off("channelSync", onChannelSync));
+            this.subscribe(channel);
+        }
+        entry.handlers.add(handlers);
+        let detached = false;
+        return () => {
+            if (detached)
+                return;
+            detached = true;
+            entry.handlers.delete(handlers);
+            if (entry.handlers.size === 0) {
+                entry.cleanup.forEach((fn) => fn());
+                this.channelRegistry.delete(key);
+                this.unsubscribe(channel);
+            }
+        };
+    }
     syncChannel(channel) {
         if (!this.isConnected()) {
             void this.connect();
@@ -237,22 +306,22 @@ class GatewayClient {
                 this.resubscribeAll();
                 break;
             case "ChannelSync":
-                this.emit("channelSync", message.d);
+                this.emit("channelSync", this.stamp(message.d, "channelSync"));
                 break;
             case "MessageCreate":
-                this.emit("messageCreate", (0, snowflake_1.addTimestampToMessage)(message.d));
+                this.emit("messageCreate", this.stamp((0, snowflake_1.addTimestampToMessage)(message.d), "messageCreate"));
                 break;
             case "MessageUpdate":
-                this.emit("messageUpdate", (0, snowflake_1.addTimestampToMessage)(message.d.message), message.d.request_data);
+                this.emit("messageUpdate", this.stamp((0, snowflake_1.addTimestampToMessage)(message.d.message), "messageUpdate"), message.d.request_data);
                 break;
             case "AggregateUpdate":
-                this.emit("aggregateUpdate", message.d);
+                this.emit("aggregateUpdate", this.stamp(message.d, "aggregateUpdate"));
                 break;
             case "AlarmTrigger":
-                this.emit("alarmTrigger", message.d);
+                this.emit("alarmTrigger", this.stamp(message.d, "alarmTrigger"));
                 break;
             case "OneShotMessage":
-                this.emit("oneShotMessage", message.d);
+                this.emit("oneShotMessage", this.stamp(message.d, "oneShotMessage"));
                 break;
             case "ChannelSubscription":
                 this.emit("channelSubscription", message.d);

package/dist/http/rest-client.d.ts

@@ -20,6 +20,11 @@ export interface DooverClientConfig extends AuthConfig {
      * in browsers and automatically skipped in non-browser environments.
      */
     disableBrowserLifecycleHooks?: boolean;
+    /** Stable id for this client as a data source. Defaults to "cloud". Used in
+     *  `__source` provenance and `DataClientStatus.clientId`. */
+    sourceId?: string;
+    /** Optional human label for this source (UI/debug). */
+    sourceLabel?: string;
 }
 export interface RequestOptions {
     baseUrl?: string;

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { DooverClient } from "./client/doover-client";
+export { LocalAgentClient } from "./client/local-agent-client";
+export type { LocalAgentClientConfig } from "./client/local-agent-client";
+export { MultiplexClient } from "./client/multiplex-client";
+export type { MultiplexClientOptions, SourceDescriptor, RegisteredSource, MultiplexConflict, } from "./client/multiplex-client";
 export { getDooverClient, peekDooverClient, resetDooverClient, } from "./client/singleton";
 export { DooverStatsCollector } from "./client/stats";
 export type { DooverStatsSnapshot, RestStatsSnapshot, GatewayStatsSnapshot, } from "./client/stats";
@@ -12,6 +16,17 @@ export { NotificationsApi } from "./apis/notifications-api";
 export { PermissionsApi } from "./apis/permissions-api";
 export { ProcessorsApi } from "./apis/processors-api";
 export { TurnApi } from "./apis/turn-api";
+export { UsersApi } from "./apis/users-api";
+export { RpcDispatcher } from "./rpc/rpc-dispatcher";
+export type { SendRpcOptions } from "./rpc/rpc-dispatcher";
+export { DooverRpcError } from "./rpc/errors";
+export type { ChannelHandlers } from "./gateway/gateway-client";
+export type { RpcStatsSnapshot } from "./client/stats";
+export { ALL_CAPABILITIES } from "./client/capabilities";
+export type { Capability } from "./client/capabilities";
+export { UnsupportedCapabilityError, AmbiguousWriteError } from "./client/errors";
+export type { DataClient, AgentScope, DataClientStatus, DataClientConnectionState, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, TurnApiLike, UsersApiLike, GatewayClientLike, RpcDispatcherLike, } from "./client/data-client";
+export type { SourceProvenance, SourceProvenanceViaRest, SourceProvenanceViaGateway, } from "./types/provenance";
 export { DooverAuth } from "./auth/doover-auth";
 export { CookieAuth } from "./auth/cookie-auth";
 export { DooverTokenAuth } from "./auth/doover-token-auth";

package/dist/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.DooverClient = void 0;
+exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.MultiplexClient = exports.LocalAgentClient = exports.DooverClient = void 0;
 var doover_client_1 = require("./client/doover-client");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_1.DooverClient; } });
+var local_agent_client_1 = require("./client/local-agent-client");
+Object.defineProperty(exports, "LocalAgentClient", { enumerable: true, get: function () { return local_agent_client_1.LocalAgentClient; } });
+var multiplex_client_1 = require("./client/multiplex-client");
+Object.defineProperty(exports, "MultiplexClient", { enumerable: true, get: function () { return multiplex_client_1.MultiplexClient; } });
 var singleton_1 = require("./client/singleton");
 Object.defineProperty(exports, "getDooverClient", { enumerable: true, get: function () { return singleton_1.getDooverClient; } });
 Object.defineProperty(exports, "peekDooverClient", { enumerable: true, get: function () { return singleton_1.peekDooverClient; } });
@@ -29,6 +33,17 @@ var processors_api_1 = require("./apis/processors-api");
 Object.defineProperty(exports, "ProcessorsApi", { enumerable: true, get: function () { return processors_api_1.ProcessorsApi; } });
 var turn_api_1 = require("./apis/turn-api");
 Object.defineProperty(exports, "TurnApi", { enumerable: true, get: function () { return turn_api_1.TurnApi; } });
+var users_api_1 = require("./apis/users-api");
+Object.defineProperty(exports, "UsersApi", { enumerable: true, get: function () { return users_api_1.UsersApi; } });
+var rpc_dispatcher_1 = require("./rpc/rpc-dispatcher");
+Object.defineProperty(exports, "RpcDispatcher", { enumerable: true, get: function () { return rpc_dispatcher_1.RpcDispatcher; } });
+var errors_1 = require("./rpc/errors");
+Object.defineProperty(exports, "DooverRpcError", { enumerable: true, get: function () { return errors_1.DooverRpcError; } });
+var capabilities_1 = require("./client/capabilities");
+Object.defineProperty(exports, "ALL_CAPABILITIES", { enumerable: true, get: function () { return capabilities_1.ALL_CAPABILITIES; } });
+var errors_2 = require("./client/errors");
+Object.defineProperty(exports, "UnsupportedCapabilityError", { enumerable: true, get: function () { return errors_2.UnsupportedCapabilityError; } });
+Object.defineProperty(exports, "AmbiguousWriteError", { enumerable: true, get: function () { return errors_2.AmbiguousWriteError; } });
 var doover_auth_1 = require("./auth/doover-auth");
 Object.defineProperty(exports, "DooverAuth", { enumerable: true, get: function () { return doover_auth_1.DooverAuth; } });
 var cookie_auth_1 = require("./auth/cookie-auth");
@@ -37,18 +52,18 @@ var doover_token_auth_1 = require("./auth/doover-token-auth");
 Object.defineProperty(exports, "DooverTokenAuth", { enumerable: true, get: function () { return doover_token_auth_1.DooverTokenAuth; } });
 var auth_profile_1 = require("./auth/auth-profile");
 Object.defineProperty(exports, "AuthProfile", { enumerable: true, get: function () { return auth_profile_1.AuthProfile; } });
-var errors_1 = require("./auth/errors");
-Object.defineProperty(exports, "DooverAuthError", { enumerable: true, get: function () { return errors_1.DooverAuthError; } });
+var errors_3 = require("./auth/errors");
+Object.defineProperty(exports, "DooverAuthError", { enumerable: true, get: function () { return errors_3.DooverAuthError; } });
 var build_auth_1 = require("./auth/build-auth");
 Object.defineProperty(exports, "buildAuth", { enumerable: true, get: function () { return build_auth_1.buildAuth; } });
 var gateway_client_1 = require("./gateway/gateway-client");
 Object.defineProperty(exports, "GatewayClient", { enumerable: true, get: function () { return gateway_client_1.GatewayClient; } });
 var rest_client_1 = require("./http/rest-client");
 Object.defineProperty(exports, "RestClient", { enumerable: true, get: function () { return rest_client_1.RestClient; } });
-var errors_2 = require("./http/errors");
-Object.defineProperty(exports, "DooverApiError", { enumerable: true, get: function () { return errors_2.DooverApiError; } });
-Object.defineProperty(exports, "DooverGatewayError", { enumerable: true, get: function () { return errors_2.DooverGatewayError; } });
-Object.defineProperty(exports, "DooverValidationError", { enumerable: true, get: function () { return errors_2.DooverValidationError; } });
+var errors_4 = require("./http/errors");
+Object.defineProperty(exports, "DooverApiError", { enumerable: true, get: function () { return errors_4.DooverApiError; } });
+Object.defineProperty(exports, "DooverGatewayError", { enumerable: true, get: function () { return errors_4.DooverGatewayError; } });
+Object.defineProperty(exports, "DooverValidationError", { enumerable: true, get: function () { return errors_4.DooverValidationError; } });
 var doover_data_provider_1 = require("./viewer/doover-data-provider");
 Object.defineProperty(exports, "DooverDataProvider", { enumerable: true, get: function () { return doover_data_provider_1.DooverDataProvider; } });
 var path_parsing_1 = require("./viewer/path-parsing");

package/dist/react/context.d.ts

@@ -1,19 +1,23 @@
 import { type ReactNode } from "react";
-import { DooverClient } from "../client/doover-client";
+import type { DataClient } from "../client/data-client";
 export interface DooverProviderProps {
-    client: DooverClient;
+    client: DataClient;
     children: ReactNode;
 }
 /**
- * Wraps a React subtree with a `DooverClient` instance so downstream hooks
+ * Wraps a React subtree with a `DataClient` instance so downstream hooks
  * (`useDooverClient`, `useChannelAggregate`, etc.) can read it from context.
  *
  * Pair with a `@tanstack/react-query` `<QueryClientProvider>` in the same tree —
  * the hooks call `useQueryClient()` internally and will throw without one.
+ *
+ * Accepts any `DataClient` implementation — `DooverClient` (single cloud source),
+ * `LocalAgentClient` (single local device), or `MultiplexClient` (fan-out across
+ * multiple sources).
  */
 export declare function DooverProvider({ client, children }: DooverProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
- * Read the `DooverClient` from context. Throws if called outside a
+ * Read the `DataClient` from context. Throws if called outside a
  * `<DooverProvider>`.
  */
-export declare function useDooverClient(): DooverClient;
+export declare function useDooverClient(): DataClient;

package/dist/react/context.js

@@ -6,17 +6,21 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const DooverClientContext = (0, react_1.createContext)(null);
 /**
- * Wraps a React subtree with a `DooverClient` instance so downstream hooks
+ * Wraps a React subtree with a `DataClient` instance so downstream hooks
  * (`useDooverClient`, `useChannelAggregate`, etc.) can read it from context.
  *
  * Pair with a `@tanstack/react-query` `<QueryClientProvider>` in the same tree —
  * the hooks call `useQueryClient()` internally and will throw without one.
+ *
+ * Accepts any `DataClient` implementation — `DooverClient` (single cloud source),
+ * `LocalAgentClient` (single local device), or `MultiplexClient` (fan-out across
+ * multiple sources).
  */
 function DooverProvider({ client, children }) {
     return ((0, jsx_runtime_1.jsx)(DooverClientContext.Provider, { value: client, children: children }));
 }
 /**
- * Read the `DooverClient` from context. Throws if called outside a
+ * Read the `DataClient` from context. Throws if called outside a
  * `<DooverProvider>`.
  */
 function useDooverClient() {

package/dist/react/index.d.ts

@@ -1,5 +1,7 @@
 export { DooverProvider, useDooverClient } from "./context";
 export type { DooverProviderProps } from "./context";
+export type { DataClientStatus, DataClientConnectionState, AgentScope } from "../client/data-client";
+export { useClientStatus } from "./useClientStatus";
 export { useConnectionState } from "./useConnectionState";
 export type { ConnectionState, ConnectionStatus } from "./useConnectionState";
 export { useAgentConnections, agentConnectionsQueryKey, } from "./useAgentConnections";
@@ -9,6 +11,7 @@ export { useChannelAggregate, channelAggregateQueryKey, } from "./useChannelAggr
 export type { UseChannelAggregateOptions, UseChannelAggregateResult, } from "./useChannelAggregate";
 export { useAgentChannel } from "./useAgentChannel";
 export { useSendMessage } from "./useSendMessage";
+export type { UseSendMessageOptions } from "./useSendMessage";
 export { useUpdateAggregate } from "./useUpdateAggregate";
 export type { UseUpdateAggregateOptions } from "./useUpdateAggregate";
 export { useUpdateMessage } from "./useUpdateMessage";

package/dist/react/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_1.useDooverClient; } });
+var useClientStatus_1 = require("./useClientStatus");
+Object.defineProperty(exports, "useClientStatus", { enumerable: true, get: function () { return useClientStatus_1.useClientStatus; } });
 var useConnectionState_1 = require("./useConnectionState");
 Object.defineProperty(exports, "useConnectionState", { enumerable: true, get: function () { return useConnectionState_1.useConnectionState; } });
 var useAgentConnections_1 = require("./useAgentConnections");

package/dist/react/useChannelAggregate.d.ts

@@ -1,7 +1,7 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { Aggregate } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
-export declare function channelAggregateQueryKey(agentId: string | undefined, channelName: string | undefined): readonly ["doover", "agent", string | undefined, "channel", string | undefined];
+export declare function channelAggregateQueryKey(agentId: string | undefined, channelName: string | undefined, sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "src", string];
 /**
  * Shape returned by `useChannelAggregate`. Shadows the react-query
  * `data` field with the unwrapped aggregate payload (`TData`) so the
@@ -39,6 +39,13 @@ export interface UseChannelAggregateOptions {
      * `AggregateUpdate` events.
      */
     fetchInitial?: boolean;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
 }
 /**
  * Fetch a channel's aggregate and keep it live via the gateway. Incoming

package/dist/react/useChannelAggregate.js

@@ -7,8 +7,9 @@ const react_query_1 = require("@tanstack/react-query");
 const errors_1 = require("../http/errors");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
-function channelAggregateQueryKey(agentId, channelName) {
-    return ["doover", "agent", agentId, "channel", channelName];
+function channelAggregateQueryKey(agentId, channelName, sources) {
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    return ["doover", "agent", agentId, "channel", channelName, "src", sourceDim];
 }
 /**
  * Fetch a channel's aggregate and keep it live via the gateway. Incoming
@@ -25,20 +26,37 @@ function useChannelAggregate(identifier, options) {
     const client = (0, context_1.useDooverClient)();
     const queryClient = (0, react_query_1.useQueryClient)();
     const { agentId, channelName } = identifier;
-    const key = channelAggregateQueryKey(agentId, channelName);
+    const sources = options?.sources;
+    const key = channelAggregateQueryKey(agentId, channelName, sources);
     const fetchInitial = options?.fetchInitial ?? true;
     const onAggregate = (0, react_1.useCallback)((aggregate) => {
         queryClient.setQueryData(key, aggregate);
     }, 
-    // The key array is structurally stable per (agentId, channelName).
+    // The key array is structurally stable per (agentId, channelName, sourceDim).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [queryClient, agentId, channelName]);
+    [queryClient, agentId, channelName, sources?.join(",")]);
     (0, useChannelSubscription_1.useChannelSubscription)(identifier, { onAggregate });
     const query = (0, react_query_1.useQuery)({
         queryKey: key,
         enabled: fetchInitial && !!agentId && !!channelName,
         staleTime: Infinity,
-        queryFn: () => client.viewer.getAggregate(identifier),
+        queryFn: async () => {
+            if (!agentId || !channelName)
+                return undefined;
+            const id = { agentId, channelName };
+            // Pass `{ sources }` as a trailing bag only when set. The TypeScript
+            // overloads don't declare it, so we cast through `never` — the runtime
+            // implementation reads it via `...args: unknown[]`.
+            const sourcesArg = sources ? { sources } : undefined;
+            const channel = sourcesArg
+                ? await client.channels.getChannel(id, sourcesArg)
+                : await client.channels.getChannel(id);
+            if (channel.aggregate)
+                return channel.aggregate;
+            return (sourcesArg
+                ? await client.aggregates.getAggregate(id, sourcesArg)
+                : await client.aggregates.getAggregate(id));
+        },
         // A 404 means the aggregate doesn't exist — retrying won't change that,
         // and the caller needs the error promptly to render an empty/"not
         // installed" state. Fall back to the react-query default (3 retries) for

package/dist/react/useChannelMessage.d.ts

@@ -1,10 +1,17 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { JSONValue, MessageAttachment, MessageStructure } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
-export declare function channelMessageQueryKey(agentId: string | undefined, channelName: string | undefined, messageId: string | undefined): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "message", string | undefined];
+export declare function channelMessageQueryKey(agentId: string | undefined, channelName: string | undefined, messageId: string | undefined, sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "message", string | undefined, "src", string];
 export interface UseChannelMessageOptions {
     /** If false, skip subscribing for live message-update events. Defaults true. */
     liveUpdates?: boolean;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
 }
 /**
  * Shape returned by `useChannelMessage`. Mirrors `UseChannelAggregateResult`:

package/dist/react/useChannelMessage.js

@@ -6,7 +6,8 @@ const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
-function channelMessageQueryKey(agentId, channelName, messageId) {
+function channelMessageQueryKey(agentId, channelName, messageId, sources) {
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
     return [
         "doover",
         "agent",
@@ -15,6 +16,8 @@ function channelMessageQueryKey(agentId, channelName, messageId) {
         channelName,
         "message",
         messageId,
+        "src",
+        sourceDim,
     ];
 }
 /**
@@ -35,15 +38,16 @@ function useChannelMessage(identifier, messageId, options) {
     const queryClient = (0, react_query_1.useQueryClient)();
     const { agentId, channelName } = identifier;
     const liveUpdates = options?.liveUpdates ?? true;
-    const key = channelMessageQueryKey(agentId, channelName, messageId);
+    const sources = options?.sources;
+    const key = channelMessageQueryKey(agentId, channelName, messageId, sources);
     const onMessageUpdate = (0, react_1.useCallback)((message) => {
         if (message.id !== messageId)
             return;
         queryClient.setQueryData(key, message);
     }, 
-    // The key array is structurally stable per (agentId, channelName, messageId).
+    // The key array is structurally stable per (agentId, channelName, messageId, sourceDim).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [queryClient, agentId, channelName, messageId]);
+    [queryClient, agentId, channelName, messageId, sources?.join(",")]);
     // Cover the case where the caller has the id before the create event has
     // landed on this client — patch the cache when it shows up.
     const onMessage = (0, react_1.useCallback)((message) => {
@@ -52,13 +56,20 @@ function useChannelMessage(identifier, messageId, options) {
         queryClient.setQueryData(key, message);
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [queryClient, agentId, channelName, messageId]);
+    [queryClient, agentId, channelName, messageId, sources?.join(",")]);
     (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates && messageId ? identifier : undefined, { onMessage, onMessageUpdate });
     const query = (0, react_query_1.useQuery)({
         queryKey: key,
         enabled: !!agentId && !!channelName && !!messageId,
         staleTime: Infinity,
-        queryFn: () => client.messages.getMessage(agentId, channelName, messageId),
+        queryFn: () => {
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            return (sourcesArg
+                ? client.messages.getMessage(agentId, channelName, messageId, sourcesArg)
+                : client.messages.getMessage(agentId, channelName, messageId));
+        },
     });
     const message = query.data;
     const { data: _ignored, ...rest } = query;

package/dist/react/useChannelMessages.d.ts

@@ -1,7 +1,7 @@
 import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
 import type { MessageStructure } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
-export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages"] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", {
+export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[], sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
     readonly fields: string[];
 }];
 export interface UseChannelMessagesOptions {
@@ -35,6 +35,13 @@ export interface UseChannelMessagesOptions {
      * bound this will walk the channel back to its first message.
      */
     autoPaginate?: boolean;
+    /**
+     * Restrict to these source ids on a `MultiplexClient`. Ignored for a plain
+     * `DooverClient` or `LocalAgentClient`. When set, the query key is
+     * source-dimensioned so data from different source subsets is cached
+     * independently.
+     */
+    sources?: string[];
 }
 type Page<TData> = MessageStructure<TData>[];
 export interface UseChannelMessagesResult<TData> extends Omit<UseInfiniteQueryResult<InfiniteData<Page<TData>>>, "data"> {

package/dist/react/useChannelMessages.js

@@ -6,8 +6,11 @@ const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
-function channelMessagesQueryKey(agentId, channelName, fields) {
-    const key = ["doover", "agent", agentId, "channel", channelName, "messages"];
+function channelMessagesQueryKey(agentId, channelName, fields, sources) {
+    // Source-dimension the key (multiplex source subsets cache independently);
+    // "*" means "all/unspecified" for a plain DooverClient/LocalAgentClient.
+    const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
+    const key = ["doover", "agent", agentId, "channel", channelName, "messages", "src", sourceDim];
     if (!fields || fields.length === 0)
         return key;
     // A `field_name`-filtered request returns a different message stream than
@@ -33,7 +36,8 @@ function useChannelMessages(identifier, options) {
     const initialBefore = options?.initialBefore;
     const after = options?.after;
     const autoPaginate = options?.autoPaginate ?? false;
-    const key = channelMessagesQueryKey(agentId, channelName, fields);
+    const sources = options?.sources;
+    const key = channelMessagesQueryKey(agentId, channelName, fields, sources);
     const onMessage = (0, react_1.useCallback)((message) => {
         // This cache entry is scoped to `fields`; the gateway delivers every
         // message on the channel, so drop live pushes whose payload doesn't
@@ -59,7 +63,7 @@ function useChannelMessages(identifier, options) {
         });
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [queryClient, agentId, channelName, fields?.join(",")]);
+    [queryClient, agentId, channelName, fields?.join(","), sources?.join(",")]);
     (0, useChannelSubscription_1.useChannelSubscription)(liveUpdates ? identifier : undefined, { onMessage });
     const query = (0, react_query_1.useInfiniteQuery)({
         queryKey: key,
@@ -68,13 +72,23 @@ function useChannelMessages(identifier, options) {
         initialPageParam: initialBefore,
         getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
         queryFn: async ({ pageParam }) => {
-            const page = await client.viewer.getMessages(identifier, {
+            if (!agentId || !channelName)
+                return [];
+            const id = { agentId, channelName };
+            const params = {
                 ...(typeof pageParam === "string" ? { before: pageParam } : {}),
                 ...(limit !== undefined ? { limit } : {}),
                 ...(fields && fields.length > 0 ? { field_name: fields } : {}),
                 ...(after !== undefined ? { after } : {}),
-            });
-            return (page ?? []);
+                order: "asc",
+            };
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `never` since the TypeScript overloads don't declare it.
+            const sourcesArg = sources ? { sources } : undefined;
+            const page = sourcesArg
+                ? await client.messages.listMessages(id, params, sourcesArg)
+                : await client.messages.listMessages(id, params);
+            return page;
         },
     });
     (0, react_1.useEffect)(() => {

package/dist/react/useChannelSubscription.d.ts

@@ -9,6 +9,12 @@ export interface ChannelSubscriptionHandlers {
      */
     onMessageUpdate?: (message: MessageStructure, request_data?: JSONValue) => void;
     onAggregate?: (aggregate: Aggregate) => void;
+    /**
+     * Reserved for future use. The composite gateway already routes by
+     * `channel.agent_id`, so this option is a no-op in v1. Pass it for
+     * forward-compatibility; it has no effect on the subscription.
+     */
+    sources?: string[];
 }
 /**
  * Attach live-update handlers to a channel for the lifetime of the host