doover-js 0.11.0 → 0.13.0

package/dist/esm/client/multiplex-client.js

@@ -0,0 +1,842 @@
+import { dedupeBy, mergeMessages } from "./multiplex-merge.js";
+import { mergeBatchResponses } from "../types/batch.js";
+import { UnsupportedCapabilityError, AmbiguousWriteError } from "./errors.js";
+import { extractSnowflakeId } from "../utils/snowflake.js";
+import { MultiplexGateway } from "./multiplex-gateway.js";
+/** "<subclient>.<method>" → spec. Drives the generic non-core facades. */
+const NONCORE_METHODS = {
+    // alarms
+    "alarms.listAgentAlarms": { cap: "alarms.read", kind: "read-fanout-first", agentScoped: true },
+    "alarms.listAlarms": { cap: "alarms.read", kind: "read-fanout-first", agentScoped: true },
+    "alarms.getAlarm": { cap: "alarms.read", kind: "read-fanout-first", agentScoped: true },
+    "alarms.createAlarm": { cap: "alarms.write", kind: "write-route", agentScoped: true },
+    "alarms.putAlarm": { cap: "alarms.write", kind: "write-route", agentScoped: true },
+    "alarms.patchAlarm": { cap: "alarms.write", kind: "write-route", agentScoped: true },
+    "alarms.deleteAlarm": { cap: "alarms.write", kind: "write-route", agentScoped: true },
+    // connections
+    "connections.getAgentConnections": { cap: "connections.read", kind: "read-fanout-first", agentScoped: true },
+    "connections.getAgentConnectionHistory": { cap: "connections.read", kind: "read-fanout-first", agentScoped: true },
+    "connections.getAgentSubscriptionHistory": { cap: "connections.read", kind: "read-fanout-first", agentScoped: true },
+    "connections.getConnection": { cap: "connections.read", kind: "read-fanout-first", agentScoped: false },
+    "connections.getChannelSubscriptions": { cap: "connections.read", kind: "read-fanout-first", agentScoped: true },
+    "connections.syncConnection": { cap: "connections.write", kind: "write-route", agentScoped: true },
+    // notifications (reads)
+    "notifications.getAgentNotifications": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: true },
+    "notifications.getAgentNotificationEndpoints": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: true },
+    "notifications.getAgentNotificationEndpointSummaries": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: true },
+    "notifications.getAgentNotificationSubscriptions": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: true },
+    "notifications.getAgentDefaultNotificationSubscriptions": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: true },
+    "notifications.getAgentNotificationSubscribers": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: true },
+    "notifications.getWebPushPublicKey": { cap: "notifications.read", kind: "read-fanout-first", agentScoped: false },
+    // notifications (writes)
+    "notifications.createNotificationEndpoint": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.updateNotificationEndpoint": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.deleteNotificationEndpoint": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.testNotificationEndpoint": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.createNotificationSubscription": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.updateDefaultNotificationSubscription": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.deleteDefaultNotificationSubscription": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.updateNotificationSubscription": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.deleteNotificationSubscription": { cap: "notifications.write", kind: "write-route", agentScoped: true },
+    "notifications.updateMeWebPushEndpoint": { cap: "notifications.write", kind: "write-route", agentScoped: false },
+    // permissions
+    "permissions.getAgentPermission": { cap: "permissions.read", kind: "read-fanout-first", agentScoped: true },
+    "permissions.getAgentPermissionDebug": { cap: "permissions.read", kind: "read-fanout-first", agentScoped: true },
+    "permissions.syncPermissions": { cap: "permissions.write", kind: "write-route", agentScoped: false },
+    // processors
+    "processors.getScheduleInfo": { cap: "processors.read", kind: "read-fanout-first", agentScoped: false },
+    "processors.getScheduleInfoAlias": { cap: "processors.read", kind: "read-fanout-first", agentScoped: false },
+    "processors.getProcessorSubscriptionInfo": { cap: "processors.read", kind: "read-fanout-first", agentScoped: false },
+    "processors.getProcessorSubscriptionInfoAlias": { cap: "processors.read", kind: "read-fanout-first", agentScoped: false },
+    "processors.createProcessorSchedule": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.deleteProcessorSchedule": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.regenerateScheduleToken": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.createProcessorSubscription": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.deleteProcessorSubscription": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.createIngestionEndpoint": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.deleteIngestionEndpoint": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    "processors.invokeIngestionEndpoint": { cap: "processors.write", kind: "write-route", agentScoped: true },
+    // turn / users
+    "turn.createTurnToken": { cap: "turn.credentials", kind: "read-fanout-first", agentScoped: false },
+    "users.getMe": { cap: "users.me", kind: "read-fanout-first", agentScoped: false },
+};
+export class MultiplexClient {
+    constructor(options) {
+        this.registry = new Map();
+        this.eventListeners = new Map();
+        this.capabilitiesCache = null;
+        this.lastConflicts = [];
+        this.maxConflicts = 50;
+        this.statusListeners = new Set();
+        /** sourceId → member unsubscribe fn for its onStatusChange. */
+        this.memberStatusUnsubs = new Map();
+        this.factory = options.factory;
+        this.disconnectOnDisable = options.disconnectOnDisable ?? true;
+        this.clientId = options.clientId ?? "multiplex";
+        for (const d of options.register ?? [])
+            this.registerSource(d);
+        this.agents = this.makeAgentsFacade();
+        this.channels = this.makeChannelsFacade();
+        this.messages = this.makeMessagesFacade();
+        this.aggregates = this.makeAggregatesFacade();
+        this.alarms = this.makeReadFacade("alarms");
+        this.connections = this.makeReadFacade("connections");
+        this.notifications = this.makeReadFacade("notifications");
+        this.permissions = this.makeReadFacade("permissions");
+        this.processors = this.makeReadFacade("processors");
+        this.turn = this.makeReadFacade("turn");
+        this.users = this.makeReadFacade("users");
+        this.rpc = this.makeRpcFacade();
+        this.gateway = this.makeCompositeGateway();
+        const toEnable = options.enableAll
+            ? (options.register ?? []).map((d) => d.id)
+            : (options.enable ?? []);
+        for (const id of toEnable)
+            this.enableSource(id);
+    }
+    // ===== registry / activation =====
+    registerSource(descriptor) {
+        const existing = this.registry.get(descriptor.id);
+        if (existing) {
+            existing.descriptor = { ...existing.descriptor, ...descriptor };
+            return;
+        }
+        this.registry.set(descriptor.id, { descriptor, enabled: false });
+    }
+    setActiveSources(idsOrDescriptors) {
+        const wanted = new Set();
+        for (const item of idsOrDescriptors) {
+            if (typeof item === "string") {
+                if (!this.registry.has(item)) {
+                    throw new Error(`MultiplexClient.setActiveSources: unknown source id "${item}" — pass a descriptor to auto-register.`);
+                }
+                wanted.add(item);
+            }
+            else {
+                this.registerSource(item);
+                wanted.add(item.id);
+            }
+        }
+        const currentlyEnabled = new Set([...this.registry.values()].filter((s) => s.enabled).map((s) => s.descriptor.id));
+        const same = wanted.size === currentlyEnabled.size && [...wanted].every((id) => currentlyEnabled.has(id));
+        if (same)
+            return;
+        for (const id of currentlyEnabled)
+            if (!wanted.has(id))
+                this.disableSource(id, { silent: true });
+        for (const id of wanted)
+            if (!currentlyEnabled.has(id))
+                this.enableSource(id, { silent: true });
+        this.invalidateCapabilities();
+        this.emit("change");
+    }
+    enableSource(id, opts) {
+        const src = this.registry.get(id);
+        if (!src)
+            throw new Error(`MultiplexClient.enableSource: unknown source id "${id}".`);
+        if (src.enabled)
+            return;
+        if (!src.client) {
+            const built = this.factory(src.descriptor);
+            if (built instanceof Promise) {
+                src.enabled = true;
+                void built.then((client) => {
+                    src.client = client;
+                    this.attachMemberListeners(src);
+                    this.invalidateCapabilities();
+                    this.emit("change");
+                });
+                if (!opts?.silent) {
+                    this.invalidateCapabilities();
+                    this.emit("change");
+                }
+                return;
+            }
+            src.client = built;
+        }
+        src.enabled = true;
+        this.attachMemberListeners(src);
+        if (!opts?.silent) {
+            this.invalidateCapabilities();
+            this.emit("change");
+        }
+    }
+    disableSource(id, opts) {
+        const src = this.registry.get(id);
+        if (!src || !src.enabled)
+            return;
+        src.enabled = false;
+        this.detachMemberListeners(src);
+        if (this.disconnectOnDisable && src.client) {
+            try {
+                src.client.gateway.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+        if (!opts?.silent) {
+            this.invalidateCapabilities();
+            this.emit("change");
+        }
+    }
+    removeSource(id) {
+        const src = this.registry.get(id);
+        if (!src)
+            return;
+        if (src.enabled)
+            this.disableSource(id, { silent: true });
+        else if (src.client) {
+            try {
+                src.client.gateway.disconnect();
+            }
+            catch { /* ignore */ }
+        }
+        this.registry.delete(id);
+        this.invalidateCapabilities();
+        this.emit("change");
+    }
+    getActiveSources() {
+        return [...this.registry.values()].filter((s) => s.enabled);
+    }
+    getRegisteredSources() {
+        return [...this.registry.values()];
+    }
+    /** Enabled members that have a built `client`. */
+    enabledClients() {
+        return this.getActiveSources()
+            .filter((s) => !!s.client)
+            .map((s) => ({ id: s.descriptor.id, src: s, client: s.client }));
+    }
+    // ===== events =====
+    on(event, handler) {
+        (this.eventListeners.get(event) ?? this.eventListeners.set(event, new Set()).get(event)).add(handler);
+    }
+    off(event, handler) {
+        this.eventListeners.get(event)?.delete(handler);
+    }
+    emit(event, ...args) {
+        this.eventListeners.get(event)?.forEach((h) => h(...args));
+        // keep status observers in sync whenever the member set changes
+        if (event === "change")
+            this.emitStatus();
+    }
+    invalidateCapabilities() { this.capabilitiesCache = null; }
+    attachMemberListeners(src) {
+        if (!src.client)
+            return;
+        if (this.memberStatusUnsubs.has(src.descriptor.id))
+            return;
+        const unsub = src.client.onStatusChange(() => this.emitStatus());
+        this.memberStatusUnsubs.set(src.descriptor.id, unsub);
+    }
+    detachMemberListeners(src) {
+        const unsub = this.memberStatusUnsubs.get(src.descriptor.id);
+        if (unsub) {
+            unsub();
+            this.memberStatusUnsubs.delete(src.descriptor.id);
+        }
+    }
+    makeCompositeGateway() {
+        const host = {
+            gatewayMembers: () => this.enabledClients()
+                .filter(({ client }) => client.supports("gateway.subscribe"))
+                .map(({ id, client }) => ({ id, gateway: client.gateway })),
+            gatewayMembersForAgent: (agentId) => this.membersForAgentWithCapability(agentId, "gateway.subscribe")
+                .map(({ id, client }) => ({ id, gateway: client.gateway })),
+        };
+        return new MultiplexGateway(host);
+    }
+    // ===== helpers =====
+    /** Resolve the optional `{ sources?: string[] }` bag from a method's trailing
+     *  arg: returns the candidate members, narrowed to `sources` if given (each
+     *  must be enabled), still capability-filtered by the caller. The bag is the
+     *  LAST argument if it is a plain object with a `sources` array. */
+    splitSourcesOption(args) {
+        const last = args[args.length - 1];
+        if (last && typeof last === "object" && !Array.isArray(last) && Array.isArray(last.sources)) {
+            return { args: args.slice(0, -1), sources: last.sources };
+        }
+        return { args };
+    }
+    candidates(agentId, cap, sources) {
+        let members = this.membersForAgentWithCapability(agentId, cap);
+        if (sources) {
+            const allow = new Set(sources);
+            members = members.filter((m) => allow.has(m.id));
+        }
+        return members;
+    }
+    /** Extract the agent id from the first positional arg (string or identifier object). */
+    extractAgentId(args) {
+        return typeof args[0] === "string" ? args[0] : args[0]?.agentId;
+    }
+    /** Throw if no enabled member supports `cap` at all (regardless of agent). */
+    assertSomeMemberSupports(cap) {
+        if (!this.enabledClients().some(({ client }) => client.supports(cap))) {
+            throw new UnsupportedCapabilityError(cap, this.clientId);
+        }
+    }
+    isNotFound(err) {
+        return !!err && typeof err === "object" && err.status === 404;
+    }
+    requiredMessagesCapability(params) {
+        if (params?.after)
+            return "messages.listHistorical";
+        if (params?.before) {
+            try {
+                const { timestamp: ts } = extractSnowflakeId(params.before);
+                if (typeof ts === "number" && ts < Date.now() - 24 * 60 * 60 * 1000)
+                    return "messages.listHistorical";
+            }
+            catch { /* not a valid snowflake, treat as latest */ }
+        }
+        return "messages.list";
+    }
+    unsupportedMethod(_method, cap) {
+        return () => Promise.reject(new UnsupportedCapabilityError(cap, this.clientId));
+    }
+    /**
+     * Route a cross-agent batch mutation.
+     *
+     * A batch can name agents served by different members, so unlike
+     * `routedWrite` there is no single target. Each item is resolved to its own
+     * member using the same rules (unsupported and ambiguous both throw), the
+     * batch is split into one sub-batch per member, and results are stitched
+     * back into the caller's original item order.
+     *
+     * Resolution happens for every item up front so an unroutable item fails
+     * the whole call before any member is written to, rather than leaving a
+     * half-applied batch behind.
+     */
+    routedBatchWrite(method, cap) {
+        const self = this;
+        return async function (...rawArgs) {
+            const { args, sources } = self.splitSourcesOption(rawArgs);
+            const items = (args[0] ?? []);
+            if (!Array.isArray(items) || items.length === 0) {
+                return { items: [], count: 0, succeeded: 0, failed: 0 };
+            }
+            const groups = new Map();
+            items.forEach((item, index) => {
+                let members = self.candidates(item.agent_id, cap, sources);
+                if (sources && sources.length === 1) {
+                    const only = members.find((m) => m.id === sources[0]);
+                    if (!only)
+                        throw new UnsupportedCapabilityError(cap, sources[0]);
+                    members = [only];
+                }
+                if (members.length === 0)
+                    throw new UnsupportedCapabilityError(cap, self.clientId);
+                if (members.length > 1) {
+                    throw new AmbiguousWriteError(cap, members.map((m) => m.id));
+                }
+                const target = members[0];
+                const group = groups.get(target.id) ?? {
+                    client: target.client,
+                    items: [],
+                    indices: [],
+                };
+                group.items.push(item);
+                group.indices.push(index);
+                groups.set(target.id, group);
+            });
+            const subclient = method.split(".")[0];
+            const fnName = method.split(".")[1];
+            const results = new Array(items.length);
+            for (const group of groups.values()) {
+                const fn = group.client[subclient][fnName];
+                const response = (await fn.apply(group.client[subclient], [
+                    group.items,
+                ]));
+                group.indices.forEach((originalIndex, i) => {
+                    const item = response.items[i];
+                    // A member that returns a short list would otherwise leave holes;
+                    // record an explicit failure so `count` stays consistent.
+                    results[originalIndex] = item ?? {
+                        agent_id: group.items[i].agent_id,
+                        channel_name: group.items[i].channel_name ?? "",
+                        success: false,
+                        error: "no result returned for batch item",
+                    };
+                });
+            }
+            return mergeBatchResponses([
+                { items: results, count: results.length, succeeded: 0, failed: 0 },
+            ]);
+        };
+    }
+    guessNonCoreCap(subclient) {
+        switch (subclient) {
+            case "alarms": return "alarms.read";
+            case "connections": return "connections.read";
+            case "notifications": return "notifications.read";
+            case "permissions": return "permissions.read";
+            case "processors": return "processors.read";
+            case "turn": return "turn.credentials";
+            case "users": return "users.me";
+            default: return "channels.get";
+        }
+    }
+    recordConflict(method, agentId, channelName, values) {
+        // Only a conflict if the values differ (cheap structural compare).
+        const json = values.map((v) => JSON.stringify(v.value, (k, val) => (k === "__source" ? undefined : val)));
+        const allEqual = json.every((j) => j === json[0]);
+        if (allEqual)
+            return;
+        const conflict = { method, agentId, channelName, sourceIds: values.map((v) => v.id), values: values.map((v) => v.value), at: Date.now() };
+        this.lastConflicts.push(conflict);
+        if (this.lastConflicts.length > this.maxConflicts)
+            this.lastConflicts.shift();
+        this.emit("conflict", conflict);
+    }
+    getLastConflicts() { return this.lastConflicts; }
+    /**
+     * Returns a method that routes a write to exactly one member:
+     *  (a) `{ sources: [oneId] }` scoping → that member;
+     *  (b) else the single enabled member that owns the targeted agent and has `cap`;
+     *  (c) else `UnsupportedCapabilityError` (none) or `AmbiguousWriteError` (>1).
+     * The targeted agent id is `args[0]` (string form) or `args[0].agentId` (identifier form).
+     * Writes are never fanned out.
+     */
+    routedWrite(method, cap) {
+        const self = this;
+        return async function (...rawArgs) {
+            const { args, sources } = self.splitSourcesOption(rawArgs);
+            const agentId = self.extractAgentId(args);
+            let members = self.candidates(agentId, cap, sources);
+            if (sources && sources.length === 1) {
+                const only = members.find((m) => m.id === sources[0]);
+                if (!only)
+                    throw new UnsupportedCapabilityError(cap, sources[0]);
+                members = [only];
+            }
+            if (members.length === 0)
+                throw new UnsupportedCapabilityError(cap, self.clientId);
+            if (members.length > 1)
+                throw new AmbiguousWriteError(cap, members.map((m) => m.id));
+            const target = members[0];
+            const subclient = method.split(".")[0];
+            const fnName = method.split(".")[1];
+            const fn = target.client[subclient][fnName];
+            return fn.apply(target.client[subclient], args);
+        };
+    }
+    /** Agent-scoped "first success" — used by messages.getTimeseries / getInvocationLogs. */
+    makeFanoutFirst(method, cap) {
+        const self = this;
+        return async function (...rawArgs) {
+            const { args, sources } = self.splitSourcesOption(rawArgs);
+            self.assertSomeMemberSupports(cap);
+            const agentId = self.extractAgentId(args);
+            const members = self.candidates(agentId, cap, sources);
+            if (members.length === 0)
+                throw new UnsupportedCapabilityError(cap, self.clientId);
+            const subclient = method.split(".")[0];
+            const fnName = method.split(".")[1];
+            let lastErr;
+            for (const m of members) {
+                try {
+                    return await m.client[subclient][fnName](...args);
+                }
+                catch (e) {
+                    lastErr = e;
+                    if (!self.isNotFound(e))
+                        throw e;
+                }
+            }
+            throw lastErr ?? new Error(`${method}: no member returned a result`);
+        };
+    }
+    /** Used by messages.getMessageAttachment — returns the first member that yields a Blob. */
+    makeBlobFanout(method, cap) {
+        const self = this;
+        return async function (...rawArgs) {
+            const { args, sources } = self.splitSourcesOption(rawArgs);
+            self.assertSomeMemberSupports(cap);
+            const agentId = self.extractAgentId(args);
+            const members = self.candidates(agentId, cap, sources);
+            if (members.length === 0)
+                throw new UnsupportedCapabilityError(cap, self.clientId);
+            const subclient = method.split(".")[0];
+            const fnName = method.split(".")[1];
+            let lastErr;
+            for (const m of members) {
+                try {
+                    return await m.client[subclient][fnName](...args);
+                }
+                catch (e) {
+                    lastErr = e;
+                    if (!self.isNotFound(e))
+                        throw e;
+                }
+            }
+            throw lastErr ?? new Error(`${method}: no member returned a result`);
+        };
+    }
+    // ===== core facades =====
+    makeChannelsFacade() {
+        const self = this;
+        return {
+            async listChannels(agentIdOrId, ...rest) {
+                const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
+                const agentId = self.extractAgentId(args);
+                self.assertSomeMemberSupports("channels.list");
+                const members = self.candidates(agentId, "channels.list", sources);
+                const perMember = await Promise.all(members.map((m) => m.client.channels.listChannels(...args)));
+                return dedupeBy([].concat(...perMember), (c) => c.name);
+            },
+            async getChannel(agentIdOrId, ...rest) {
+                const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
+                const agentId = self.extractAgentId(args);
+                const name = typeof args[0] === "string" ? args[1] : args[0].channelName;
+                self.assertSomeMemberSupports("channels.get");
+                const members = self.candidates(agentId, "channels.get", sources);
+                const settled = await Promise.allSettled(members.map((m) => m.client.channels.getChannel(...args)));
+                const ok = settled.flatMap((r, i) => r.status === "fulfilled" ? [{ value: r.value, id: members[i].id }] : (r.status === "rejected" && !self.isNotFound(r.reason) ? (() => { throw r.reason; })() : []));
+                if (ok.length === 0) {
+                    const e = new Error(`channel ${agentId}/${name} not found`);
+                    e.status = 404;
+                    throw e;
+                }
+                if (ok.length > 1)
+                    self.recordConflict("channels.getChannel", agentId, name, ok);
+                return ok[0].value;
+            },
+            createChannel: self.routedWrite("channels.createChannel", "channels.create"),
+            putChannel: self.routedWrite("channels.putChannel", "channels.create"),
+            archiveChannel: self.routedWrite("channels.archiveChannel", "channels.archive"),
+            unarchiveChannel: self.routedWrite("channels.unarchiveChannel", "channels.archive"),
+            listDataSeries: self.unsupportedMethod("channels.listDataSeries", "channels.dataSeries"),
+        };
+    }
+    makeAggregatesFacade() {
+        const self = this;
+        return {
+            async getAggregate(agentIdOrId, ...rest) {
+                const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
+                const agentId = self.extractAgentId(args);
+                const name = typeof args[0] === "string" ? args[1] : args[0].channelName;
+                self.assertSomeMemberSupports("aggregates.get");
+                const members = self.candidates(agentId, "aggregates.get", sources);
+                const settled = await Promise.allSettled(members.map((m) => m.client.aggregates.getAggregate(...args)));
+                const ok = settled.flatMap((r, i) => r.status === "fulfilled" ? [{ value: r.value, id: members[i].id }] : (r.status === "rejected" && !self.isNotFound(r.reason) ? (() => { throw r.reason; })() : []));
+                if (ok.length === 0) {
+                    const e = new Error(`aggregate ${agentId}/${name} not found`);
+                    e.status = 404;
+                    throw e;
+                }
+                if (ok.length > 1)
+                    self.recordConflict("aggregates.getAggregate", agentId, name, ok);
+                return ok[0].value;
+            },
+            putAggregate: self.routedWrite("aggregates.putAggregate", "aggregates.put"),
+            patchAggregate: self.routedWrite("aggregates.patchAggregate", "aggregates.patch"),
+            batchPatchAggregates: self.routedBatchWrite("aggregates.batchPatchAggregates", "aggregates.patch"),
+            async getAggregateAttachment(agentIdOrId, ...rest) {
+                const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
+                const agentId = self.extractAgentId(args);
+                self.assertSomeMemberSupports("aggregates.attachment");
+                const members = self.candidates(agentId, "aggregates.attachment", sources);
+                for (const m of members) {
+                    try {
+                        return await m.client.aggregates.getAggregateAttachment(...args);
+                    }
+                    catch (e) {
+                        if (!self.isNotFound(e))
+                            throw e;
+                    }
+                }
+                const e = new Error("attachment not found");
+                e.status = 404;
+                throw e;
+            },
+        };
+    }
+    makeMessagesFacade() {
+        const self = this;
+        return {
+            async listMessages(agentIdOrId, ...rest) {
+                const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
+                const agentId = self.extractAgentId(args);
+                const params = (typeof args[0] === "string" ? args[2] : args[1]);
+                const implied = self.requiredMessagesCapability(params);
+                // a member is eligible if it has the implied cap; for "latest N" that IS messages.list.
+                self.assertSomeMemberSupports(implied);
+                const members = self.candidates(agentId, implied, sources);
+                const perMember = await Promise.all(members.map((m) => m.client.messages.listMessages(...args)));
+                return mergeMessages(perMember, { order: params?.order ?? "desc", limit: params?.limit });
+            },
+            async getMessage(agentIdOrId, ...rest) {
+                const { args, sources } = self.splitSourcesOption([agentIdOrId, ...rest]);
+                const agentId = self.extractAgentId(args);
+                self.assertSomeMemberSupports("messages.get");
+                const members = self.candidates(agentId, "messages.get", sources);
+                for (const m of members) {
+                    try {
+                        return await m.client.messages.getMessage(...args);
+                    }
+                    catch (e) {
+                        if (!self.isNotFound(e))
+                            throw e;
+                    }
+                }
+                const e = new Error("message not found");
+                e.status = 404;
+                throw e;
+            },
+            postMessage: self.routedWrite("messages.postMessage", "messages.post"),
+            putMessage: self.routedWrite("messages.putMessage", "messages.put"),
+            patchMessage: self.routedWrite("messages.patchMessage", "messages.put"),
+            deleteMessage: self.routedWrite("messages.deleteMessage", "messages.delete"),
+            batchPostMessages: self.routedBatchWrite("messages.batchPostMessages", "messages.post"),
+            batchPatchMessages: self.routedBatchWrite("messages.batchPatchMessages", "messages.put"),
+            batchPutMessages: self.routedBatchWrite("messages.batchPutMessages", "messages.put"),
+            batchDeleteMessages: self.routedBatchWrite("messages.batchDeleteMessages", "messages.delete"),
+            getTimeseries: self.makeFanoutFirst("messages.getTimeseries", "messages.timeseries"),
+            getMessageAttachment: self.makeBlobFanout("messages.getMessageAttachment", "messages.attachment"),
+            getInvocationLogs: self.makeFanoutFirst("messages.getInvocationLogs", "messages.invocationLogs"),
+            createMultipartPayload(jsonPayload, attachments) {
+                // pure helper — no member needed; mirror MessagesApi.createMultipartPayload
+                const formData = new FormData();
+                formData.set("json_payload", JSON.stringify(jsonPayload));
+                attachments.forEach((attachment, index) => {
+                    formData.set(`attachment-${index}`, attachment);
+                });
+                return formData;
+            },
+        };
+    }
+    makeAgentsFacade() {
+        const self = this;
+        return {
+            async listAgents(...rawArgs) {
+                const { args, sources } = self.splitSourcesOption(rawArgs);
+                self.assertSomeMemberSupports("agents.list");
+                let members = self.enabledClients().filter(({ client }) => client.supports("agents.list"));
+                if (sources) {
+                    const allow = new Set(sources);
+                    members = members.filter((m) => allow.has(m.id));
+                }
+                const responses = await Promise.all(members.map((m) => m.client.agents.listAgents(...args)));
+                const merged = dedupeBy([].concat(...responses.map((r) => (r.agents ?? r.results ?? []))), (a) => a.id);
+                return { agents: merged, results: merged, count: merged.length };
+            },
+            async getMultiAgentMessages(channelName, ...rest) {
+                const { args, sources } = self.splitSourcesOption([channelName, ...rest]);
+                self.assertSomeMemberSupports("agents.multiAgentMessages");
+                let members = self.enabledClients().filter(({ client }) => client.supports("agents.multiAgentMessages"));
+                if (sources) {
+                    const allow = new Set(sources);
+                    members = members.filter((m) => allow.has(m.id));
+                }
+                const responses = await Promise.all(members.map((m) => m.client.agents.getMultiAgentMessages(...args)));
+                const merged = mergeMessages(responses.map((r) => r.results), { order: "desc" });
+                // Union each member's per-agent resume cursors so a paginating caller
+                // keeps walking. If one agent lives in two members with different
+                // cursors, keep the lexically-highest (newest) — resuming from the
+                // older one would skip the newer member's tail; resuming from the
+                // newer just re-fetches a few messages that dedupe by id downstream.
+                const nextCursors = {};
+                for (const r of responses) {
+                    for (const [id, cursor] of Object.entries(r.next_cursors ?? {})) {
+                        if (!(id in nextCursors) || cursor > nextCursors[id])
+                            nextCursors[id] = cursor;
+                    }
+                }
+                return {
+                    results: merged,
+                    count: merged.length,
+                    ...(Object.keys(nextCursors).length > 0 ? { next_cursors: nextCursors } : {}),
+                };
+            },
+            async getMultiAgentAggregates(channelName, ...rest) {
+                const { args, sources } = self.splitSourcesOption([channelName, ...rest]);
+                self.assertSomeMemberSupports("agents.multiAgentAggregates");
+                let members = self.enabledClients().filter(({ client }) => client.supports("agents.multiAgentAggregates"));
+                if (sources) {
+                    const allow = new Set(sources);
+                    members = members.filter((m) => allow.has(m.id));
+                }
+                const responses = await Promise.all(members.map((m) => m.client.agents.getMultiAgentAggregates(...args)));
+                const merged = dedupeBy([].concat(...responses.map((r) => r.results)), (a) => a.agent_id);
+                return { results: merged, count: merged.length };
+            },
+            getTokenState: self.makeFanoutFirst("agents.getTokenState", "agents.tokenRead"),
+            setTokenPolicy: self.routedWrite("agents.setTokenPolicy", "agents.tokenManage"),
+            setAuthLock: self.routedWrite("agents.setAuthLock", "agents.tokenManage"),
+            revokeAllTokens: self.routedWrite("agents.revokeAllTokens", "agents.tokenManage"),
+            setRevocationFloor: self.routedWrite("agents.setRevocationFloor", "agents.tokenManage"),
+            createAdhocToken: self.routedWrite("agents.createAdhocToken", "agents.tokenManage"),
+            createDeviceToken: self.routedWrite("agents.createDeviceToken", "agents.tokenManage"),
+        };
+    }
+    // ===== non-core generic facade =====
+    makeReadFacade(subclientName) {
+        const self = this;
+        return new Proxy({}, {
+            get(_t, prop) {
+                if (typeof prop !== "string")
+                    return undefined;
+                const key = `${subclientName}.${prop}`;
+                const spec = NONCORE_METHODS[key];
+                if (!spec) {
+                    // Unknown method on a non-core subclient — treat as unsupported (read).
+                    return () => Promise.reject(new UnsupportedCapabilityError(self.guessNonCoreCap(subclientName), self.clientId));
+                }
+                if (spec.kind === "write-route") {
+                    return self.routedWrite(key, spec.cap);
+                }
+                return async (...rawArgs) => {
+                    const { args, sources } = self.splitSourcesOption(rawArgs);
+                    self.assertSomeMemberSupports(spec.cap);
+                    const agentId = !spec.agentScoped ? undefined : self.extractAgentId(args);
+                    let members = self.candidates(agentId, spec.cap, sources);
+                    if (members.length === 0)
+                        throw new UnsupportedCapabilityError(spec.cap, self.clientId);
+                    let lastErr;
+                    for (const m of members) {
+                        try {
+                            return await m.client[subclientName][prop](...args);
+                        }
+                        catch (e) {
+                            lastErr = e;
+                            if (!self.isNotFound(e))
+                                throw e;
+                        }
+                    }
+                    throw lastErr ?? new Error(`${key}: no member returned a result`);
+                };
+            },
+        });
+    }
+    makeRpcFacade() {
+        const self = this;
+        const sendFn = self.routedWrite("rpc.send", "rpc.send");
+        return {
+            setStats() { },
+            send(channel, request, options) {
+                return sendFn(channel, request, options);
+            },
+        };
+    }
+    // --- DataClient: capabilities ---
+    getCapabilities() {
+        if (!this.capabilitiesCache) {
+            const u = new Set();
+            for (const { client } of this.enabledClients())
+                for (const c of client.getCapabilities())
+                    u.add(c);
+            this.capabilitiesCache = u;
+        }
+        return this.capabilitiesCache;
+    }
+    supports(cap) { return this.getCapabilities().has(cap); }
+    // --- agent-scope routing ---
+    /**
+     * Enabled members eligible for a request targeting `agentId`: those whose
+     * scope is `{ mode: "all" }` (the cloud — no enumeration), those whose list
+     * contains `agentId`, and those whose scope is still `"unknown"` (included
+     * optimistically; their scope settles for the next call). If `agentId` is
+     * undefined, all enabled members are eligible.
+     */
+    membersForAgent(agentId) {
+        const all = this.enabledClients();
+        if (agentId === undefined)
+            return all;
+        return all.filter(({ client }) => {
+            const scope = client.getKnownAgentScope();
+            if (scope === "unknown")
+                return true;
+            if (scope.mode === "all")
+                return true;
+            return scope.agentIds.includes(agentId);
+        });
+    }
+    /** Members (enabled) that both own `agentId` and advertise `cap`. */
+    membersForAgentWithCapability(agentId, cap) {
+        return this.membersForAgent(agentId).filter(({ client }) => client.supports(cap));
+    }
+    getAgentScope() {
+        return Promise.all(this.enabledClients().map(({ client }) => client.getAgentScope())).then((scopes) => {
+            if (scopes.some((s) => s.mode === "all"))
+                return { mode: "all" };
+            const ids = new Set();
+            for (const s of scopes)
+                if (s.mode === "list")
+                    for (const id of s.agentIds)
+                        ids.add(id);
+            return { mode: "list", agentIds: [...ids] };
+        });
+    }
+    getKnownAgentScope() {
+        const known = this.enabledClients().map(({ client }) => client.getKnownAgentScope());
+        if (known.some((s) => s !== "unknown" && s.mode === "all"))
+            return { mode: "all" };
+        if (known.some((s) => s === "unknown"))
+            return "unknown";
+        const ids = new Set();
+        for (const s of known)
+            if (s !== "unknown" && s.mode === "list")
+                for (const id of s.agentIds)
+                    ids.add(id);
+        return { mode: "list", agentIds: [...ids] };
+    }
+    isConnected() {
+        const gwMembers = this.enabledClients().filter(({ client }) => client.supports("gateway.subscribe"));
+        if (gwMembers.length === 0)
+            return false;
+        return gwMembers.every(({ client }) => client.isConnected());
+    }
+    getStatus() {
+        const allSources = this.getRegisteredSources();
+        const members = allSources.map((s) => ({
+            sourceId: s.descriptor.id,
+            ...(s.descriptor.label ? { label: s.descriptor.label } : {}),
+            status: s.enabled && s.client
+                ? s.client.getStatus()
+                : ({ clientId: s.descriptor.id, connected: false, state: "disconnected", agentScope: "unknown", at: Date.now() }),
+        }));
+        const enabledMembers = members.filter((m) => this.registry.get(m.sourceId)?.enabled);
+        const gwStatuses = enabledMembers
+            .filter((m) => this.registry.get(m.sourceId).client?.supports("gateway.subscribe"))
+            .map((m) => m.status);
+        const connected = this.isConnected();
+        let state;
+        if (enabledMembers.some((m) => m.status.state === "error"))
+            state = "error";
+        else if (gwStatuses.length === 0)
+            state = "disconnected";
+        else if (gwStatuses.every((s) => s.connected))
+            state = "connected";
+        else if (gwStatuses.some((s) => s.connected))
+            state = "degraded";
+        else if (gwStatuses.some((s) => s.state === "connecting"))
+            state = "connecting";
+        else
+            state = "disconnected";
+        // most-recent member values for scalar summary fields (locked decision #8)
+        const newest = enabledMembers.map((m) => m.status).sort((x, y) => y.at - x.at)[0];
+        const gatewaySession = this.gateway.getSession();
+        return {
+            clientId: this.clientId,
+            connected,
+            state,
+            session: gatewaySession ? { id: gatewaySession.session_id ?? "" } : null,
+            ...(newest?.lastEvent ? { lastEvent: newest.lastEvent } : {}),
+            latencyMs: newest?.latencyMs ?? null,
+            ...(newest?.lastError ? { lastError: newest.lastError } : {}),
+            agentScope: this.getKnownAgentScope(),
+            at: Date.now(),
+            members,
+        };
+    }
+    onStatusChange(listener) {
+        this.statusListeners.add(listener);
+        let active = true;
+        return () => { if (!active)
+            return; active = false; this.statusListeners.delete(listener); };
+    }
+    emitStatus() {
+        const snap = this.getStatus();
+        this.statusListeners.forEach((l) => l(snap));
+    }
+}