doover-js 0.5.4 → 0.6.0

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

@@ -0,0 +1,49 @@
+import type { GatewayClientLike } from "./data-client";
+import type { ChannelRef } from "../types/common";
+import type { WebSocketSession } from "../gateway/types";
+/** Minimal view of what MultiplexGateway needs from the owning multiplex. */
+export interface MultiplexGatewayHost {
+    /** Enabled members with `gateway.subscribe`. */
+    gatewayMembers(): Array<{
+        id: string;
+        gateway: GatewayClientLike;
+    }>;
+    /** Enabled members owning `agentId` that have `gateway.subscribe`. */
+    gatewayMembersForAgent(agentId: string): Array<{
+        id: string;
+        gateway: GatewayClientLike;
+    }>;
+}
+/**
+ * `GatewayClientLike` facade over the members' gateways:
+ *  - connect/disconnect/reconnect → fan out to members with `gateway.subscribe`.
+ *  - subscribe/unsubscribe/subscribeToChannel → route to owning members.
+ *  - on/off → register against every member; events forwarded.
+ *  - isConnected → all members with `gateway.subscribe` are connected.
+ *  - getSession → first connected member's session (locked decision #5).
+ *  - getSubscriptions/getSubscriptionCount → union across members.
+ */
+export declare class MultiplexGateway implements GatewayClientLike {
+    private readonly host;
+    /** consumer event handler → set of member gateways it was registered on. */
+    private readonly eventBindings;
+    constructor(host: MultiplexGatewayHost);
+    setStats(): void;
+    setProvenanceHook(): void;
+    connect(): Promise<void>;
+    disconnect(code?: number, reason?: string): void;
+    reconnect(): Promise<void>;
+    on(event: string, handler: (...a: unknown[]) => void): void;
+    off(event: string, handler: (...a: unknown[]) => void): void;
+    subscribe(channel: ChannelRef, options?: {
+        diff_only?: boolean;
+    }): void;
+    unsubscribe(channel: ChannelRef): void;
+    subscribeToChannel(channel: ChannelRef, handlers: Record<string, (...a: unknown[]) => void>): () => void;
+    syncChannel(channel: ChannelRef): void;
+    sendOneShotMessage(channel: ChannelRef, data: unknown): void;
+    getSession(): WebSocketSession | null;
+    isConnected(): boolean;
+    getSubscriptionCount(): number;
+    getSubscriptions(): ChannelRef[];
+}

package/dist/client/multiplex-gateway.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiplexGateway = void 0;
+/**
+ * `GatewayClientLike` facade over the members' gateways:
+ *  - connect/disconnect/reconnect → fan out to members with `gateway.subscribe`.
+ *  - subscribe/unsubscribe/subscribeToChannel → route to owning members.
+ *  - on/off → register against every member; events forwarded.
+ *  - isConnected → all members with `gateway.subscribe` are connected.
+ *  - getSession → first connected member's session (locked decision #5).
+ *  - getSubscriptions/getSubscriptionCount → union across members.
+ */
+class MultiplexGateway {
+    constructor(host) {
+        this.host = host;
+        /** consumer event handler → set of member gateways it was registered on. */
+        this.eventBindings = new Map();
+    }
+    setStats() { }
+    setProvenanceHook() {
+        /* No-op: provenance hooks are set on each member's concrete gateway impl by their owning
+         * DataClient (DooverClient/LocalAgentClient). The composite MultiplexGateway is never the
+         * target of a hook call. */
+    }
+    async connect() {
+        await Promise.all(this.host.gatewayMembers().map((m) => m.gateway.connect()));
+    }
+    disconnect(code, reason) {
+        for (const m of this.host.gatewayMembers())
+            m.gateway.disconnect(code, reason);
+    }
+    async reconnect() {
+        await Promise.all(this.host.gatewayMembers().map((m) => m.gateway.reconnect()));
+    }
+    on(event, handler) {
+        const perEvent = this.eventBindings.get(event) ??
+            this.eventBindings.set(event, new Map()).get(event);
+        const gws = new Set();
+        for (const m of this.host.gatewayMembers()) {
+            const gw = m.gateway;
+            gw.on(event, handler);
+            gws.add(gw);
+        }
+        perEvent.set(handler, gws);
+    }
+    off(event, handler) {
+        const gws = this.eventBindings.get(event)?.get(handler);
+        if (!gws)
+            return;
+        for (const gw of gws)
+            gw.off(event, handler);
+        this.eventBindings.get(event).delete(handler);
+    }
+    subscribe(channel, options) {
+        for (const m of this.host.gatewayMembersForAgent(channel.agent_id))
+            m.gateway.subscribe(channel, options);
+    }
+    unsubscribe(channel) {
+        for (const m of this.host.gatewayMembersForAgent(channel.agent_id))
+            m.gateway.unsubscribe(channel);
+    }
+    subscribeToChannel(channel, handlers) {
+        const offs = this.host
+            .gatewayMembersForAgent(channel.agent_id)
+            .map((m) => m.gateway.subscribeToChannel(channel, handlers));
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            offs.forEach((o) => o());
+        };
+    }
+    syncChannel(channel) {
+        for (const m of this.host.gatewayMembersForAgent(channel.agent_id))
+            m.gateway.syncChannel(channel);
+    }
+    sendOneShotMessage(channel, data) {
+        for (const m of this.host.gatewayMembersForAgent(channel.agent_id))
+            m.gateway.sendOneShotMessage(channel, data);
+    }
+    getSession() {
+        for (const m of this.host.gatewayMembers()) {
+            const s = m.gateway.getSession();
+            if (s)
+                return s;
+        }
+        return null;
+    }
+    isConnected() {
+        const members = this.host.gatewayMembers();
+        if (members.length === 0)
+            return false;
+        return members.every((m) => m.gateway.isConnected());
+    }
+    getSubscriptionCount() {
+        return this.getSubscriptions().length;
+    }
+    getSubscriptions() {
+        const seen = new Set();
+        const out = [];
+        for (const m of this.host.gatewayMembers()) {
+            for (const c of m.gateway.getSubscriptions()) {
+                const k = `${c.agent_id}/${c.name}`;
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                out.push(c);
+            }
+        }
+        return out;
+    }
+}
+exports.MultiplexGateway = MultiplexGateway;

package/dist/client/multiplex-merge.d.ts

@@ -0,0 +1,12 @@
+import type { MessageStructure } from "../types/common";
+/** Keep the first item for each key; preserve input order otherwise. */
+export declare function dedupeBy<T>(items: T[], keyOf: (item: T) => string): T[];
+/**
+ * Merge per-member message arrays: concatenate, de-dup by `id` (first member
+ * wins), sort by id to match `order` ("desc" = newest first, the cloud's
+ * native order; "asc" = oldest first), then truncate to `limit` if given.
+ */
+export declare function mergeMessages(perMember: MessageStructure[][], opts: {
+    order: "asc" | "desc";
+    limit?: number;
+}): MessageStructure[];

package/dist/client/multiplex-merge.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dedupeBy = dedupeBy;
+exports.mergeMessages = mergeMessages;
+/** Keep the first item for each key; preserve input order otherwise. */
+function dedupeBy(items, keyOf) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const k = keyOf(item);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(item);
+    }
+    return out;
+}
+/** Compare two snowflake-ish id strings numerically when possible, else lexically. */
+function compareIds(a, b) {
+    try {
+        const ba = BigInt(a);
+        const bb = BigInt(b);
+        return ba < bb ? -1 : ba > bb ? 1 : 0;
+    }
+    catch {
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+}
+/**
+ * Merge per-member message arrays: concatenate, de-dup by `id` (first member
+ * wins), sort by id to match `order` ("desc" = newest first, the cloud's
+ * native order; "asc" = oldest first), then truncate to `limit` if given.
+ */
+function mergeMessages(perMember, opts) {
+    const all = [].concat(...perMember);
+    const unique = dedupeBy(all, (m) => m.id);
+    unique.sort((x, y) => {
+        const c = compareIds(x.id, y.id);
+        return opts.order === "asc" ? c : -c;
+    });
+    return typeof opts.limit === "number" ? unique.slice(0, opts.limit) : unique;
+}

package/dist/client/provenance.d.ts

@@ -0,0 +1,60 @@
+import type { SourceProvenance } from "../types/provenance";
+/** A stamped value: adds `__source` to plain objects and their array elements.
+ *  For object values, also adds `__source` to any known nested-object props
+ *  (aggregate, message) and stamps elements of array-valued props. */
+type StampedElement<T> = T extends Record<string, unknown> ? T & {
+    __source?: SourceProvenance;
+} : T;
+type StampedProp<V> = V extends (infer E)[] ? StampedElement<E>[] : V extends Record<string, unknown> ? V & {
+    __source?: SourceProvenance;
+} : V;
+type Stamped<T> = T extends (infer E)[] ? StampedElement<E>[] : T extends Record<string, unknown> ? {
+    [K in keyof T]: StampedProp<T[K]>;
+} & {
+    __source?: SourceProvenance;
+} : T;
+/** Map a subclient type so that async methods return Stamped results. */
+export type WrappedSubclient<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Stamped<R>> : T[K];
+};
+export interface ClientIdentity {
+    id: string;
+    kind: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+interface RestContext {
+    /** e.g. "messages.listMessages" */
+    method: string;
+    /** caller inputs (agentId, channelName, params, body summary) */
+    request: Record<string, unknown>;
+    startedAt: number;
+    durationMs: number;
+    status?: number;
+}
+interface GatewayContext {
+    event: string;
+    sessionId?: string;
+}
+export declare class ProvenanceStamper {
+    private readonly identity;
+    constructor(identity: ClientIdentity);
+    stampRest<T>(value: T, ctx: RestContext): Stamped<T>;
+    stampGatewayEvent<T>(value: T, ctx: GatewayContext): Stamped<T>;
+    /** Build the full provenance envelope from a `via`. */
+    private prov;
+    /**
+     * Arrays → stamp each plain-object element. Plain objects → set `__source`,
+     * then shallow-stamp array-valued props' elements and known nested-object
+     * props (`aggregate`, `message`). Everything else (Blob, primitives,
+     * undefined, FormData, class instances) → returned unchanged.
+     */
+    private stampGraph;
+}
+/**
+ * Returns a Proxy over `api` whose methods, when they return a Promise, stamp
+ * the resolved value with `via.method = "<subclientName>.<methodName>"`.
+ * Synchronous returns (e.g. `createMultipartPayload`) pass through untouched.
+ */
+export declare function wrapSubclient<T extends object>(api: T, subclientName: string, stamper: ProvenanceStamper): WrappedSubclient<T>;
+export {};

package/dist/client/provenance.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProvenanceStamper = void 0;
+exports.wrapSubclient = wrapSubclient;
+/** Property names whose (object) value should also be stamped, for the known
+ *  gateway envelopes ({ ..., aggregate }, { ..., message }). */
+const NESTED_OBJECT_PROPS = ["aggregate", "message"];
+function isPlainObject(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    if (Array.isArray(v))
+        return false;
+    if (typeof Blob !== "undefined" && v instanceof Blob)
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+class ProvenanceStamper {
+    constructor(identity) {
+        this.identity = identity;
+    }
+    stampRest(value, ctx) {
+        const via = {
+            transport: "rest",
+            method: ctx.method,
+            request: ctx.request,
+            startedAt: ctx.startedAt,
+            durationMs: ctx.durationMs,
+            ...(ctx.status !== undefined ? { status: ctx.status } : {}),
+        };
+        return this.stampGraph(value, via);
+    }
+    stampGatewayEvent(value, ctx) {
+        const via = {
+            transport: "gateway",
+            event: ctx.event,
+            ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}),
+            receivedAt: Date.now(),
+        };
+        return this.stampGraph(value, via);
+    }
+    /** Build the full provenance envelope from a `via`. */
+    prov(via) {
+        return { client: this.identity, retrievedAt: Date.now(), via };
+    }
+    /**
+     * Arrays → stamp each plain-object element. Plain objects → set `__source`,
+     * then shallow-stamp array-valued props' elements and known nested-object
+     * props (`aggregate`, `message`). Everything else (Blob, primitives,
+     * undefined, FormData, class instances) → returned unchanged.
+     */
+    stampGraph(value, via) {
+        const prov = this.prov(via);
+        if (Array.isArray(value)) {
+            return value.map((el) => (isPlainObject(el) ? { ...el, __source: prov } : el));
+        }
+        if (!isPlainObject(value))
+            return value;
+        const out = { ...value, __source: prov };
+        for (const [k, v] of Object.entries(out)) {
+            if (k === "__source")
+                continue;
+            if (Array.isArray(v)) {
+                out[k] = v.map((el) => (isPlainObject(el) ? { ...el, __source: prov } : el));
+            }
+            else if (NESTED_OBJECT_PROPS.includes(k) && isPlainObject(v)) {
+                out[k] = { ...v, __source: prov };
+            }
+        }
+        return out;
+    }
+}
+exports.ProvenanceStamper = ProvenanceStamper;
+/**
+ * Returns a Proxy over `api` whose methods, when they return a Promise, stamp
+ * the resolved value with `via.method = "<subclientName>.<methodName>"`.
+ * Synchronous returns (e.g. `createMultipartPayload`) pass through untouched.
+ */
+function wrapSubclient(api, subclientName, stamper) {
+    return new Proxy(api, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function" || typeof prop !== "string")
+                return value;
+            const methodName = `${subclientName}.${prop}`;
+            return function (...args) {
+                const startedAt = Date.now();
+                const out = value.apply(target, args);
+                if (out instanceof Promise) {
+                    return out.then((result) => stamper.stampRest(result, {
+                        method: methodName,
+                        request: { args: summariseArgs(args) },
+                        startedAt,
+                        durationMs: Date.now() - startedAt,
+                    }));
+                }
+                return out;
+            };
+        },
+    });
+}
+/** Keep `via.request` small: drop FormData/Blob bodies, cap string length. */
+function summariseArgs(args) {
+    return args.map((a) => {
+        if (typeof FormData !== "undefined" && a instanceof FormData)
+            return "[FormData]";
+        if (typeof Blob !== "undefined" && a instanceof Blob)
+            return "[Blob]";
+        if (typeof a === "string" && a.length > 200)
+            return `${a.slice(0, 200)}…`;
+        return a;
+    });
+}

package/dist/client/stats.d.ts

@@ -26,9 +26,22 @@ export interface GatewayStatsSnapshot {
     /** Frames we've received on the gateway socket. */
     messagesReceived: number;
 }
+export interface RpcStatsSnapshot {
+    enabled: boolean;
+    totalRpcs: number;
+    pendingRpcs: number;
+    completedRpcs: number;
+    failedRpcs: number;
+    timedOutRpcs: number;
+    abortedRpcs: number;
+    averageLatencyMs: number | null;
+    lastLatencyMs: number | null;
+    peakPendingRpcs: number;
+}
 export interface DooverStatsSnapshot {
     rest: RestStatsSnapshot;
     gateway: GatewayStatsSnapshot;
+    rpc: RpcStatsSnapshot;
 }
 export declare class DooverStatsCollector {
     private enabled;
@@ -40,6 +53,15 @@ export declare class DooverStatsCollector {
     private rLastLatency;
     private gSent;
     private gReceived;
+    private rpTotal;
+    private rpPending;
+    private rpCompleted;
+    private rpFailed;
+    private rpTimedOut;
+    private rpAborted;
+    private rpLatencySum;
+    private rpLastLatency;
+    private rpPeakPending;
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
     reset(): void;
@@ -51,5 +73,7 @@ export declare class DooverStatsCollector {
     recordRestEnd(startedAt: number | null, succeeded: boolean): void;
     recordGatewaySent(): void;
     recordGatewayReceived(): void;
+    recordRpcStart(): number | null;
+    recordRpcEnd(startedAt: number | null, outcome: "success" | "error" | "timeout" | "abort"): void;
     snapshot(): DooverStatsSnapshot;
 }

package/dist/client/stats.js

@@ -18,6 +18,15 @@ class DooverStatsCollector {
         this.rLastLatency = null;
         this.gSent = 0;
         this.gReceived = 0;
+        this.rpTotal = 0;
+        this.rpPending = 0;
+        this.rpCompleted = 0;
+        this.rpFailed = 0;
+        this.rpTimedOut = 0;
+        this.rpAborted = 0;
+        this.rpLatencySum = 0;
+        this.rpLastLatency = null;
+        this.rpPeakPending = 0;
     }
     setEnabled(enabled) {
         this.enabled = enabled;
@@ -34,6 +43,15 @@ class DooverStatsCollector {
         this.rLastLatency = null;
         this.gSent = 0;
         this.gReceived = 0;
+        this.rpTotal = 0;
+        this.rpPending = 0;
+        this.rpCompleted = 0;
+        this.rpFailed = 0;
+        this.rpTimedOut = 0;
+        this.rpAborted = 0;
+        this.rpLatencySum = 0;
+        this.rpLastLatency = null;
+        this.rpPeakPending = 0;
     }
     /**
      * Record the start of a REST request. Returns the start timestamp the
@@ -68,8 +86,40 @@ class DooverStatsCollector {
             return;
         this.gReceived += 1;
     }
+    recordRpcStart() {
+        if (!this.enabled)
+            return null;
+        this.rpTotal += 1;
+        this.rpPending += 1;
+        if (this.rpPending > this.rpPeakPending)
+            this.rpPeakPending = this.rpPending;
+        return now();
+    }
+    recordRpcEnd(startedAt, outcome) {
+        if (!this.enabled || startedAt === null)
+            return;
+        this.rpPending = Math.max(0, this.rpPending - 1);
+        switch (outcome) {
+            case "success":
+                this.rpCompleted += 1;
+                break;
+            case "error":
+                this.rpFailed += 1;
+                break;
+            case "timeout":
+                this.rpTimedOut += 1;
+                break;
+            case "abort":
+                this.rpAborted += 1;
+                break;
+        }
+        const latency = now() - startedAt;
+        this.rpLastLatency = latency;
+        this.rpLatencySum += latency;
+    }
     snapshot() {
         const settled = this.rCompleted + this.rFailed;
+        const rpcSettled = this.rpCompleted + this.rpFailed + this.rpTimedOut + this.rpAborted;
         return {
             rest: {
                 enabled: this.enabled,
@@ -85,6 +135,18 @@ class DooverStatsCollector {
                 messagesSent: this.gSent,
                 messagesReceived: this.gReceived,
             },
+            rpc: {
+                enabled: this.enabled,
+                totalRpcs: this.rpTotal,
+                pendingRpcs: this.rpPending,
+                completedRpcs: this.rpCompleted,
+                failedRpcs: this.rpFailed,
+                timedOutRpcs: this.rpTimedOut,
+                abortedRpcs: this.rpAborted,
+                averageLatencyMs: rpcSettled > 0 ? this.rpLatencySum / rpcSettled : null,
+                lastLatencyMs: this.rpLastLatency,
+                peakPendingRpcs: this.rpPeakPending,
+            },
         };
     }
 }

package/dist/client/status-tracker.d.ts

@@ -0,0 +1,24 @@
+import type { AgentScope, DataClientStatus, GatewayClientLike } from "./data-client";
+/**
+ * Tracks a `DataClient`'s realtime status by subscribing to its gateway's
+ * `open` / `ready` / `close` / `wssError` events. Emits a fresh
+ * `DataClientStatus` to listeners whenever the derived snapshot changes.
+ */
+export declare class ClientStatusTracker {
+    private readonly clientId;
+    private readonly gateway;
+    private readonly knownScope;
+    private lastEvent;
+    private lastError;
+    private session;
+    private listeners;
+    private detach;
+    constructor(clientId: string, gateway: GatewayClientLike, knownScope: () => AgentScope | "unknown" | string);
+    /** Call when the agent scope resolves (so listeners re-render). */
+    notifyScopeChanged(): void;
+    getStatus(): DataClientStatus;
+    onChange(listener: (status: DataClientStatus) => void): () => void;
+    dispose(): void;
+    private transition;
+    private emit;
+}

package/dist/client/status-tracker.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientStatusTracker = void 0;
+/**
+ * Tracks a `DataClient`'s realtime status by subscribing to its gateway's
+ * `open` / `ready` / `close` / `wssError` events. Emits a fresh
+ * `DataClientStatus` to listeners whenever the derived snapshot changes.
+ */
+class ClientStatusTracker {
+    constructor(clientId, gateway, knownScope) {
+        this.clientId = clientId;
+        this.gateway = gateway;
+        this.knownScope = knownScope;
+        this.lastEvent = "init";
+        this.session = null;
+        this.listeners = new Set();
+        this.detach = [];
+        const onOpen = () => this.transition("open");
+        const onReady = (s) => {
+            if (s?.session_id)
+                this.session = { id: s.session_id };
+            this.transition("ready");
+        };
+        const onClose = () => this.transition("close");
+        const onErr = (e) => {
+            this.lastError = e?.message ?? "gateway error";
+            this.transition("error");
+        };
+        gateway.on("open", onOpen);
+        gateway.on("ready", onReady);
+        gateway.on("close", onClose);
+        gateway.on("wssError", onErr);
+        this.detach.push(() => gateway.off("open", onOpen), () => gateway.off("ready", onReady), () => gateway.off("close", onClose), () => gateway.off("wssError", onErr));
+    }
+    /** Call when the agent scope resolves (so listeners re-render). */
+    notifyScopeChanged() {
+        this.emit();
+    }
+    getStatus() {
+        const connected = this.gateway.isConnected();
+        let state;
+        if (this.lastEvent === "error")
+            state = "error";
+        else if (connected)
+            state = "connected";
+        else if (this.lastEvent === "init")
+            state = "disconnected";
+        else
+            state = "connecting"; // saw open/close but not currently connected → reconnecting
+        return {
+            clientId: this.clientId,
+            connected,
+            state,
+            session: this.session,
+            lastEvent: this.lastEvent,
+            latencyMs: null,
+            ...(this.lastError ? { lastError: this.lastError } : {}),
+            agentScope: this.knownScope(),
+            at: Date.now(),
+        };
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this.listeners.delete(listener);
+        };
+    }
+    dispose() {
+        this.detach.forEach((fn) => fn());
+        this.detach = [];
+        this.listeners.clear();
+    }
+    transition(event) {
+        this.lastEvent = event;
+        if (event !== "error") {
+            // a successful lifecycle event clears a stale error so state can recover
+            this.lastError = undefined;
+        }
+        this.emit();
+    }
+    emit() {
+        const snapshot = this.getStatus();
+        this.listeners.forEach((l) => l(snapshot));
+    }
+}
+exports.ClientStatusTracker = ClientStatusTracker;