@awarevue/agent-sdk 2.0.74 → 2.0.76

package/dist/__tests__/agent-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/agent-server.test.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const rxjs_1 = require("rxjs");
+const agent_server_1 = require("../agent-server");
+const in_memory_1 = require("../hubs/in-memory");
+const constants_1 = require("../constants");
+const in_memory_transport_1 = require("./in-memory-transport");
+let msgSeq = 0;
+const envelope = (from, payload) => ({
+    ...payload,
+    id: `msg-${++msgSeq}`,
+    from,
+    version: constants_1.AGENT_PROTOCOL_VERSION,
+    on: Date.now(),
+});
+const registerPayload = (agentId) => envelope(agentId, {
+    kind: 'register',
+    providers: {
+        'test-provider': {
+            title: 'Test Provider',
+            configSchema: {},
+            configDefault: {},
+        },
+    },
+});
+const startRsPayload = (agentId, requestId) => envelope(agentId, { kind: 'start-rs', requestId });
+const stopRsPayload = (agentId, requestId) => envelope(agentId, { kind: 'stop-rs', requestId });
+/**
+ * Connects a fake agent to the hub and returns the agent's side of the transport.
+ */
+function connectAgent(hub, peerId) {
+    const [agentSide, serverSide] = (0, in_memory_transport_1.createTransportPair)();
+    hub.addPeer(peerId, serverSide);
+    return agentSide;
+}
+/**
+ * Subscribe BEFORE sending — in-memory transports deliver synchronously,
+ * so the reply arrives during send() and is missed if subscribed after.
+ */
+function sendAndAwait(agent, msg, replyKind) {
+    const p = (0, rxjs_1.firstValueFrom)(agent.messages$.pipe((0, rxjs_1.filter)((m) => m.kind === replyKind), (0, rxjs_1.timeout)(1000)));
+    agent.send(msg);
+    return p;
+}
+/* ------------------------------------------------------------------ */
+/*  Tests                                                             */
+/* ------------------------------------------------------------------ */
+(0, vitest_1.describe)('AgentServer', () => {
+    let hub;
+    let server;
+    (0, vitest_1.beforeEach)(() => {
+        hub = new in_memory_1.InMemoryHub();
+        msgSeq = 0;
+    });
+    (0, vitest_1.afterEach)(() => {
+        server === null || server === void 0 ? void 0 : server.finalize();
+        hub === null || hub === void 0 ? void 0 : hub.close();
+    });
+    // ── Registration ──────────────────────────────────────────────────
+    (0, vitest_1.describe)('registration', () => {
+        (0, vitest_1.it)('should resolve agentId from msg.from on register', async () => {
+            const registered = [];
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ agentId, accept }) => {
+                    registered.push(agentId);
+                    accept();
+                },
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            const reply = await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            (0, vitest_1.expect)(reply.kind).toBe('register-rs');
+            (0, vitest_1.expect)(registered).toEqual(['my-agent']);
+        });
+        (0, vitest_1.it)('should allow rejecting registration', async () => {
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ reject }) => {
+                    reject('not allowed');
+                },
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            const reply = await sendAndAwait(agent, registerPayload('bad-agent'), 'error-rs');
+            (0, vitest_1.expect)(reply.kind).toBe('error-rs');
+            (0, vitest_1.expect)(reply.error).toBe('not allowed');
+        });
+        (0, vitest_1.it)('should handle multiple agents with different peer IDs', async () => {
+            const registered = [];
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ agentId, accept }) => {
+                    registered.push(agentId);
+                    accept();
+                },
+            });
+            server.init();
+            const agentA = connectAgent(hub, 1);
+            const agentB = connectAgent(hub, 2);
+            await sendAndAwait(agentA, registerPayload('agent-alpha'), 'register-rs');
+            await sendAndAwait(agentB, registerPayload('agent-beta'), 'register-rs');
+            (0, vitest_1.expect)(registered).toContain('agent-alpha');
+            (0, vitest_1.expect)(registered).toContain('agent-beta');
+        });
+    });
+    // ── Start / Stop ──────────────────────────────────────────────────
+    (0, vitest_1.describe)('start and stop', () => {
+        (0, vitest_1.it)('should route startAgent by agentId to correct peer', async () => {
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+            });
+            server.init();
+            const agentA = connectAgent(hub, 1);
+            const agentB = connectAgent(hub, 2);
+            await sendAndAwait(agentA, registerPayload('agent-alpha'), 'register-rs');
+            await sendAndAwait(agentB, registerPayload('agent-beta'), 'register-rs');
+            // subscribe before sending
+            const startPromise = (0, rxjs_1.firstValueFrom)(agentB.messages$.pipe((0, rxjs_1.filter)((m) => m.kind === 'start'), (0, rxjs_1.timeout)(1000)));
+            server.startAgent({
+                agentId: 'agent-beta',
+                provider: 'test-provider',
+                config: { url: 'http://test' },
+                lastEventForeignRef: null,
+                lastEventTimestamp: null,
+            });
+            const startMsg = await startPromise;
+            (0, vitest_1.expect)(startMsg.kind).toBe('start');
+            (0, vitest_1.expect)(startMsg.provider).toBe('test-provider');
+        });
+        (0, vitest_1.it)('should fire onStarted when agent replies with start-rs', async () => {
+            const started = [];
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+                onStarted: ({ agentId }) => started.push(agentId),
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            agent.send(startRsPayload('my-agent', 'req-1'));
+            (0, vitest_1.expect)(started).toEqual(['my-agent']);
+        });
+        (0, vitest_1.it)('should fire onStopped when agent replies with stop-rs', async () => {
+            const stopped = [];
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+                onStopped: ({ agentId }) => stopped.push(agentId),
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            agent.send(stopRsPayload('my-agent', 'req-2'));
+            (0, vitest_1.expect)(stopped).toEqual(['my-agent']);
+        });
+        (0, vitest_1.it)('should send stop to the correct agent', async () => {
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            const stopPromise = (0, rxjs_1.firstValueFrom)(agent.messages$.pipe((0, rxjs_1.filter)((m) => m.kind === 'stop'), (0, rxjs_1.timeout)(1000)));
+            server.stopAgent('my-agent', 'test-provider');
+            const stopMsg = await stopPromise;
+            (0, vitest_1.expect)(stopMsg.kind).toBe('stop');
+            (0, vitest_1.expect)(stopMsg.provider).toBe('test-provider');
+        });
+    });
+    // ── Disconnect ────────────────────────────────────────────────────
+    (0, vitest_1.describe)('disconnect', () => {
+        (0, vitest_1.it)('should fire onUnregistered with agentId when peer disconnects after registration', async () => {
+            const unregistered = [];
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+                onUnregistered: ({ agentId }) => unregistered.push(agentId),
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            agent.close();
+            (0, vitest_1.expect)(unregistered).toEqual(['my-agent']);
+        });
+        (0, vitest_1.it)('should not fire onUnregistered for peers that never registered', async () => {
+            const unregistered = [];
+            server = new agent_server_1.AgentServer(hub, {
+                onUnregistered: ({ agentId }) => unregistered.push(agentId),
+            });
+            server.init();
+            // connect and immediately disconnect without registering
+            const agent = connectAgent(hub, 1);
+            agent.close();
+            await new Promise((r) => setTimeout(r, 10));
+            (0, vitest_1.expect)(unregistered).toEqual([]);
+        });
+        (0, vitest_1.it)('should clean up maps after disconnect', async () => {
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            (0, vitest_1.expect)(server.getAgentSender('my-agent')).not.toBeNull();
+            agent.close();
+            (0, vitest_1.expect)(server.getAgentSender('my-agent')).toBeNull();
+        });
+    });
+    // ── Protocol validation ───────────────────────────────────────────
+    (0, vitest_1.describe)('protocol validation', () => {
+        (0, vitest_1.it)('should reject messages with wrong protocol version', async () => {
+            server = new agent_server_1.AgentServer(hub);
+            server.init();
+            const notifications = [];
+            server.notifications$.subscribe((n) => notifications.push(n));
+            const agent = connectAgent(hub, 1);
+            const badMsg = {
+                kind: 'register',
+                providers: {},
+                id: 'bad-1',
+                from: 'bad-agent',
+                version: 999,
+                on: Date.now(),
+            };
+            const reply = await sendAndAwait(agent, badMsg, 'error-rs');
+            (0, vitest_1.expect)(reply.kind).toBe('error-rs');
+            (0, vitest_1.expect)(reply.error).toContain('Incompatible protocol version');
+            (0, vitest_1.expect)(notifications.some((n) => n.includes('incompatible'))).toBe(true);
+        });
+    });
+    // ── messages$ stream ──────────────────────────────────────────────
+    (0, vitest_1.describe)('messages$ stream', () => {
+        (0, vitest_1.it)('should include agentId alongside peer in emitted messages', async () => {
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+            });
+            server.init();
+            const emittedPromise = (0, rxjs_1.firstValueFrom)(server.messages$.pipe((0, rxjs_1.timeout)(1000)));
+            const agent = connectAgent(hub, 42);
+            agent.send(registerPayload('stream-agent'));
+            const emitted = await emittedPromise;
+            (0, vitest_1.expect)(emitted.peer).toBe(42);
+            (0, vitest_1.expect)(emitted.agentId).toBe('stream-agent');
+            (0, vitest_1.expect)(emitted.msg.kind).toBe('register');
+        });
+    });
+    // ── finalize ──────────────────────────────────────────────────────
+    (0, vitest_1.describe)('finalize', () => {
+        (0, vitest_1.it)('should clear internal maps on finalize', async () => {
+            server = new agent_server_1.AgentServer(hub, {
+                onRegister: ({ accept }) => accept(),
+            });
+            server.init();
+            const agent = connectAgent(hub, 1);
+            await sendAndAwait(agent, registerPayload('my-agent'), 'register-rs');
+            (0, vitest_1.expect)(server.getAgentSender('my-agent')).not.toBeNull();
+            server.finalize();
+            (0, vitest_1.expect)(server.getAgentSender('my-agent')).toBeNull();
+        });
+    });
+});

package/dist/__tests__/in-memory-transport.d.ts

@@ -0,0 +1,10 @@
+import { DuplexTransport } from '../transport_types';
+/**
+ * Creates a linked pair of in-process DuplexTransports.
+ * Writing to one side is immediately readable on the other.
+ * No serialization, no network — pure in-memory for testing.
+ */
+export declare function createTransportPair<TA, TB>(): [
+    DuplexTransport<TA, TB>,
+    DuplexTransport<TB, TA>
+];

package/dist/__tests__/in-memory-transport.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTransportPair = createTransportPair;
+const rxjs_1 = require("rxjs");
+/**
+ * Creates a linked pair of in-process DuplexTransports.
+ * Writing to one side is immediately readable on the other.
+ * No serialization, no network — pure in-memory for testing.
+ */
+function createTransportPair() {
+    const aToB = new rxjs_1.Subject();
+    const bToA = new rxjs_1.Subject();
+    const aConnected = new rxjs_1.BehaviorSubject(true);
+    const bConnected = new rxjs_1.BehaviorSubject(true);
+    const close = () => {
+        aConnected.next(false);
+        bConnected.next(false);
+        aConnected.complete();
+        bConnected.complete();
+        aToB.complete();
+        bToA.complete();
+    };
+    const sideA = {
+        connected$: aConnected.asObservable(),
+        messages$: bToA.asObservable(),
+        send: (msg) => {
+            if (aConnected.value)
+                aToB.next(msg);
+        },
+        close,
+    };
+    const sideB = {
+        connected$: bConnected.asObservable(),
+        messages$: aToB.asObservable(),
+        send: (msg) => {
+            if (bConnected.value)
+                bToA.next(msg);
+        },
+        close,
+    };
+    return [sideA, sideB];
+}

package/dist/agent-app-with-defaults.d.ts

@@ -0,0 +1,16 @@
+import { FromAgent, FromServer, Message } from '@awarevue/api-types';
+import { Agent } from './agent';
+import { AgentApp, AgentOptions } from './agent-app';
+import { DuplexTransport } from './transport_types';
+export type AgentAppWithDefaultsOptions = Omit<AgentOptions, 'transport'> & {
+    url: string;
+    apiKey: string;
+    transport?: DuplexTransport<Message<FromServer>, Message<FromAgent>>;
+};
+/**
+ * Creates an AgentApp instance with default transport settings (WS transport wrapped in a logging decorator) if no custom transport is provided.
+ * @param agent The agent instance to use.
+ * @param options Configuration options for the AgentApp.
+ * @returns A configured AgentApp instance.
+ */
+export declare function createAgentApp(agent: Agent, options: AgentAppWithDefaultsOptions): AgentApp;

package/dist/agent-app-with-defaults.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentApp = createAgentApp;
+const agent_app_1 = require("./agent-app");
+const logging_1 = require("./transports/logging");
+const ws_1 = require("./transports/ws");
+const ws_json_encoder_1 = require("./transports/ws-json-encoder");
+/**
+ * Creates an AgentApp instance with default transport settings (WS transport wrapped in a logging decorator) if no custom transport is provided.
+ * @param agent The agent instance to use.
+ * @param options Configuration options for the AgentApp.
+ * @returns A configured AgentApp instance.
+ */
+function createAgentApp(agent, options) {
+    const { url, apiKey, transport, ...rest } = options;
+    const finalTransport = transport !== null && transport !== void 0 ? transport : new logging_1.LoggingDuplexTransport(new ws_json_encoder_1.WsJsonEncoder(new ws_1.WsDuplexTransport({
+        url,
+        headers: {
+            Authorization: `APIKey ${apiKey}`,
+        },
+    })));
+    return new agent_app_1.AgentApp(agent, { ...rest, transport: finalTransport });
+}

package/dist/agent-protocol.d.ts

@@ -27,6 +27,6 @@ export declare class AgentProtocol<D extends Direction> {
     constructor(transport: DuplexTransport<Message<Inbound<D>>, Message<Outbound<D>>>, options: AgentProtocolOptions);
     getReply$: <K extends RequestKind>(payload: Extract<Outbound<D>, {
         kind: K;
-    }>) => Observable<Message<PayloadByKind[ResponseKind<K>]>>;
+    }>, timeoutMs?: number) => Observable<Message<PayloadByKind[ResponseKind<K>]>>;
     send: (payload: Outbound<D>) => void;
 }

package/dist/agent-protocol.js

@@ -15,17 +15,24 @@ class AgentProtocol {
             version: constants_1.AGENT_PROTOCOL_VERSION,
             on: Date.now(),
         });
-        this.getReply$ = (payload) => {
+        this.getReply$ = (payload, timeoutMs) => {
             const responseKind = api_types_1.ReplyKindByRequestKind[payload.kind];
-            const reply$ = (id) => this.transport.messages$.pipe((0, rxjs_1.mergeMap)((message) => {
-                if (message.kind === 'error-rs' && message.requestId === id) {
+            const reply$ = (id) => this.transport.messages$.pipe(
+            // pass through only messages with matching requestId (it could be response, error or progress update)
+            (0, rxjs_1.filter)((message) => 'requestId' in message && message.requestId === id), (0, rxjs_1.mergeMap)((message) => {
+                // if the agent responded with an error message related to our request, throw an error to fail the stream
+                if (message.kind === 'error-rs') {
                     const error = message.error;
                     return (0, rxjs_1.throwError)(() => new Error(`Server failed to process message ${payload.kind}: ${error}`));
                 }
                 return (0, rxjs_1.of)(message);
-            }), (0, rxjs_1.filter)((message) => message.kind === responseKind &&
-                'requestId' in message &&
-                message.requestId === id), (0, rxjs_1.take)(1), (0, rxjs_1.timeout)(this.options.replyTimeout || 10000));
+            }), 
+            // enforce timeout (progress updates will reset the timer, but if no messages arrive for `timeoutMs` duration, the request is considered failed)
+            (0, rxjs_1.timeout)(timeoutMs || this.options.replyTimeout || 10000), 
+            // pass through only the final response message (filter out progress updates)
+            (0, rxjs_1.filter)((message) => message.kind === responseKind), 
+            // we only expect one response message, so complete the stream after the response arrives
+            (0, rxjs_1.take)(1));
             return (0, rxjs_1.of)(this.addEnvelope({ ...payload, id: AgentProtocol.nextId() })).pipe(
             // send the message to the agent
             (0, rxjs_1.tap)((p) => this.transport.send(p)), 

package/dist/agent-server.d.ts

@@ -0,0 +1,50 @@
+import { FromAgent, FromServer, Message, RegisterRq, StartServiceRq } from '@awarevue/api-types';
+import { HubTransport, PeerId } from './transport_types';
+import { AgentProtocol } from './agent-protocol';
+import { Subject } from 'rxjs';
+export interface OnUnregisteredEventArgs {
+    agentId: string;
+    reason?: string;
+}
+export type OnRegisterEventArgs = {
+    agentId: string;
+    accept: () => void;
+    reject: (reason: string) => void;
+} & Omit<RegisterRq, 'kind'>;
+export type OnStoppedEventArgs = {
+    agentId: string;
+};
+export type OnStartedEventArgs = {
+    agentId: string;
+};
+export type StartAgentArgs = {
+    agentId: string;
+} & Omit<StartServiceRq, 'kind'>;
+export type AgentServerOptions = {
+    /** Timeout for awaiting replies to sent messages (default 10s) */
+    replyTimeout?: number;
+    onRegister?: (args: OnRegisterEventArgs) => void;
+    onUnregistered?: (args: OnUnregisteredEventArgs) => void;
+    onStarted?: (args: OnStartedEventArgs) => void;
+    onStopped?: (args: OnStoppedEventArgs) => void;
+};
+export declare class AgentServer<TPeer extends PeerId = string> {
+    private readonly hub;
+    private readonly options;
+    readonly notifications$: Subject<string>;
+    readonly messages$: Subject<{
+        msg: Message<FromAgent>;
+        peer: TPeer;
+        agentId: string;
+    }>;
+    private sub;
+    private readonly _agentToPeer;
+    private readonly _peerToAgent;
+    constructor(hub: HubTransport<Message<FromAgent>, Message<FromServer>, TPeer>, options?: AgentServerOptions);
+    init(): void;
+    startAgent({ agentId, ...rest }: StartAgentArgs): void;
+    stopAgent(agentId: string, provider: string): void;
+    finalize(): void;
+    getAgentSender(agentId: string): AgentProtocol<'server'> | null;
+    private getPeerSender;
+}

package/dist/agent-server.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentServer = void 0;
+const api_types_1 = require("@awarevue/api-types");
+const agent_protocol_1 = require("./agent-protocol");
+const rxjs_1 = require("rxjs");
+const constants_1 = require("./constants");
+class AgentServer {
+    constructor(hub, options = {}) {
+        this.hub = hub;
+        this.options = options;
+        this.notifications$ = new rxjs_1.Subject();
+        this.messages$ = new rxjs_1.Subject();
+        this.sub = null;
+        this._agentToPeer = new Map();
+        this._peerToAgent = new Map();
+    }
+    init() {
+        if (this.sub) {
+            return;
+        }
+        const processMessages$ = this.hub.messages$.pipe(
+        // validate
+        (0, rxjs_1.map)(({ msg, peer }) => ({ msg, peer, isValid: (0, api_types_1.isMessageFromAgent)(msg) })), (0, rxjs_1.tap)(({ msg, peer, isValid }) => {
+            var _a;
+            const id = (_a = msg.id) !== null && _a !== void 0 ? _a : 'unknown';
+            if (msg.version !== constants_1.AGENT_PROTOCOL_VERSION) {
+                this.notifications$.next(`Agent ${msg.from} has incompatible protocol version: ${msg.version}`);
+                const protocol = this.getPeerSender(peer);
+                protocol === null || protocol === void 0 ? void 0 : protocol.send({
+                    kind: 'error-rs',
+                    requestId: id,
+                    error: `Incompatible protocol version. Expected ${constants_1.AGENT_PROTOCOL_VERSION} but got ${msg.version}`,
+                });
+            }
+            else if (!isValid) {
+                // log
+                const issues = (0, api_types_1.getAgentMessageIssues)(msg).join(', ');
+                this.notifications$.next(`Received invalid message from agent ${peer}: ${issues}`);
+                const sender = this.getPeerSender(peer);
+                sender === null || sender === void 0 ? void 0 : sender.send({
+                    kind: 'error-rs',
+                    requestId: id,
+                    error: issues,
+                });
+                return;
+            }
+        }), 
+        // dismiss invalid protocol messages
+        (0, rxjs_1.filter)(({ msg, isValid }) => msg.version === constants_1.AGENT_PROTOCOL_VERSION && isValid), 
+        // forward valid messages to the messages$ stream
+        (0, rxjs_1.tap)((m) => {
+            var _a, _b, _c, _d, _e, _f;
+            const agentId = m.msg.from;
+            // if this is a registration message, establish the agentId ↔ peer mapping
+            if (m.msg.kind === 'register') {
+                this._agentToPeer.set(agentId, m.peer);
+                this._peerToAgent.set(m.peer, agentId);
+                this.messages$.next({ ...m, agentId });
+                (_b = (_a = this.options).onRegister) === null || _b === void 0 ? void 0 : _b.call(_a, {
+                    ...m.msg,
+                    agentId,
+                    reject: (reason) => {
+                        const protocol = this.getPeerSender(m.peer);
+                        protocol === null || protocol === void 0 ? void 0 : protocol.send({
+                            kind: 'error-rs',
+                            requestId: m.msg.id,
+                            error: reason,
+                        });
+                        this._agentToPeer.delete(agentId);
+                        this._peerToAgent.delete(m.peer);
+                    },
+                    accept: () => {
+                        const protocol = this.getPeerSender(m.peer);
+                        protocol === null || protocol === void 0 ? void 0 : protocol.send({
+                            kind: 'register-rs',
+                            requestId: m.msg.id,
+                        });
+                    },
+                });
+            }
+            else {
+                this.messages$.next({ ...m, agentId });
+                if (m.msg.kind === 'start-rs') {
+                    (_d = (_c = this.options).onStarted) === null || _d === void 0 ? void 0 : _d.call(_c, { agentId });
+                }
+                else if (m.msg.kind === 'stop-rs') {
+                    (_f = (_e = this.options).onStopped) === null || _f === void 0 ? void 0 : _f.call(_e, { agentId });
+                }
+            }
+        }));
+        const processConnections$ = this.hub.peerEvents$.pipe((0, rxjs_1.filter)((event) => event.type === 'leave'), (0, rxjs_1.tap)(({ peer, reason }) => {
+            var _a, _b;
+            const agentId = this._peerToAgent.get(peer);
+            this.notifications$.next(`Peer ${peer}${agentId ? ` (agent: ${agentId})` : ''} left: ${reason !== null && reason !== void 0 ? reason : 'unknown reason'}`);
+            // clean up maps
+            if (agentId) {
+                this._peerToAgent.delete(peer);
+                this._agentToPeer.delete(agentId);
+                (_b = (_a = this.options).onUnregistered) === null || _b === void 0 ? void 0 : _b.call(_a, {
+                    agentId,
+                    reason: reason,
+                });
+            }
+        }));
+        this.sub = (0, rxjs_1.merge)(processMessages$, processConnections$).subscribe();
+    }
+    startAgent({ agentId, ...rest }) {
+        const protocol = this.getAgentSender(agentId);
+        protocol === null || protocol === void 0 ? void 0 : protocol.send({ kind: 'start', ...rest });
+    }
+    stopAgent(agentId, provider) {
+        const protocol = this.getAgentSender(agentId);
+        protocol === null || protocol === void 0 ? void 0 : protocol.send({ kind: 'stop', provider });
+    }
+    finalize() {
+        var _a;
+        (_a = this.sub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.sub = null;
+        this._agentToPeer.clear();
+        this._peerToAgent.clear();
+    }
+    getAgentSender(agentId) {
+        const peer = this._agentToPeer.get(agentId);
+        if (peer === undefined)
+            return null;
+        return this.getPeerSender(peer);
+    }
+    getPeerSender(peer) {
+        var _a;
+        const connection = this.hub.connection(peer);
+        if (!connection) {
+            return null;
+        }
+        const agentId = (_a = this._peerToAgent.get(peer)) !== null && _a !== void 0 ? _a : `${peer}`;
+        return new agent_protocol_1.AgentProtocol(connection, {
+            replyTimeout: this.options.replyTimeout,
+            id: agentId,
+        });
+    }
+}
+exports.AgentServer = AgentServer;

package/dist/default-validator.d.ts

@@ -7,4 +7,4 @@ export declare const createValidator: <T extends Agent>(agent: T) => (context: C
     objectKind?: "person" | "zone" | "schedule" | "device" | "accessRule" | undefined;
     objectId?: string | undefined;
     index?: number | undefined;
-}[], Record<"accessRule" | "schedule" | "person" | "device" | "zone", Record<string, Record<string, unknown>>>]>;
+}[], Record<"accessRule" | "schedule" | "person" | "zone" | "device", Record<string, Record<string, unknown>>>]>;

package/dist/hubs/in-memory.js

@@ -2,15 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryHub = void 0;
 const rxjs_1 = require("rxjs");
-const operators_1 = require("rxjs/operators");
 class InMemoryHub {
     constructor() {
         this.peerEventsSubject = new rxjs_1.Subject();
         this.messagesSubject = new rxjs_1.Subject();
         this.peers = new Map();
         this.peerSubs = new Map();
-        this.peerEvents$ = this.peerEventsSubject.asObservable().pipe((0, operators_1.share)());
-        this.messages$ = this.messagesSubject.asObservable().pipe((0, operators_1.share)());
+        this.peerEvents$ = this.peerEventsSubject.asObservable();
+        this.messages$ = this.messagesSubject.asObservable();
     }
     addPeer(peerId, conn) {
         // defensive: if peer already exists, clean it first

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './agent-app';
+export * from './agent-app-with-defaults';
+export * from './agent-server';
 export * from './agent';
 export * from './constants';
 export * from './agent-protocol';

package/dist/index.js

@@ -15,6 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./agent-app"), exports);
+__exportStar(require("./agent-app-with-defaults"), exports);
+__exportStar(require("./agent-server"), exports);
 __exportStar(require("./agent"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./agent-protocol"), exports);

package/dist/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "git+https://github.com/Linc-Security-Systems/aware-essentials.git"
   },
-  "version": "2.0.74",
+  "version": "2.0.76",
   "description": "SDK for building Agent implementations that speak the agent protocol.",
   "author": "Yaser Awajan",
   "license": "MIT",
@@ -26,17 +26,17 @@
   "scripts": {
     "build": "tsc -p tsconfig.json  && cp package.json dist/",
     "prepublishOnly": "yarn build",
-    "test": "echo \"add unit tests here\"",
+    "test": "vitest run",
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "lint:fix": "yarn lint --fix"
   },
   "peerDependencies": {
-    "@awarevue/api-types": "2.0.74",
+    "@awarevue/api-types": "2.0.76",
     "rxjs": "^7.8.2",
     "ws": "^8"
   },
   "devDependencies": {
-    "@awarevue/api-types": "2.0.74",
+    "@awarevue/api-types": "2.0.76",
     "@types/node": "^20.12.7",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.31.1",
@@ -46,6 +46,7 @@
     "eslint-plugin-import": "^2.31.0",
     "rxjs": "7.8.2",
     "typescript": "^5.8.3",
+    "vitest": "^4.1.4",
     "ws": "^8",
     "zod": "3.25.76"
   },

package/dist/transports/index.d.ts

@@ -1,2 +1,3 @@
 export * from './ws';
+export * from './ws-json-encoder';
 export * from './logging';

package/dist/transports/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ws"), exports);
+__exportStar(require("./ws-json-encoder"), exports);
 __exportStar(require("./logging"), exports);

package/dist/transports/logging.js

@@ -16,7 +16,7 @@ class LoggingDuplexTransport {
         this.inner = inner;
         this.label = (_a = opts.label) !== null && _a !== void 0 ? _a : 'transport';
         this.sink =
-            (_b = opts.logger) !== null && _b !== void 0 ? _b : ((direction, label, msg) => console.log(`[${label}] ${direction}`, JSON.stringify(msg, null, 2)));
+            (_b = opts.logger) !== null && _b !== void 0 ? _b : ((direction, label, msg) => console.log(`[${label}] ${direction}`, JSON.stringify(msg)));
         this.connected$ = inner.connected$;
         // Tap into the incoming stream before exposing it to consumers.
         this.messages$ = inner.messages$.pipe((0, operators_1.tap)((msg) => this.sink('IN', this.label, msg)));

package/dist/transports/ws-json-encoder.d.ts

@@ -0,0 +1,12 @@
+import { Observable } from 'rxjs';
+import { DuplexTransport } from '../transport_types';
+import { FromAgent, FromServer, Message } from '@awarevue/api-types';
+export declare class WsJsonEncoder implements DuplexTransport<Message<FromServer | FromAgent>, Message<FromAgent | FromServer>> {
+    private defaultDeserializer;
+    private defaultSerializer;
+    readonly connected$: Observable<boolean>;
+    readonly messages$: Observable<Message<FromServer | FromAgent>>;
+    readonly send: (msg: Message<FromAgent | FromServer>) => void;
+    readonly close: () => void;
+    constructor(decoratee: DuplexTransport<string, string>);
+}

package/dist/transports/ws-json-encoder.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsJsonEncoder = void 0;
+const rxjs_1 = require("rxjs");
+class WsJsonEncoder {
+    constructor(decoratee) {
+        this.defaultDeserializer = (raw) => {
+            const wsShape = JSON.parse(raw);
+            return {
+                kind: wsShape.event,
+                ...wsShape.data,
+            };
+        };
+        this.defaultSerializer = (msg) => {
+            const { kind, ...data } = msg;
+            const wsShape = {
+                event: kind,
+                data,
+            };
+            return JSON.stringify(wsShape);
+        };
+        this.connected$ = decoratee.connected$;
+        this.messages$ = decoratee.messages$.pipe((0, rxjs_1.map)((raw) => this.defaultDeserializer(raw)), (0, rxjs_1.catchError)(() => rxjs_1.EMPTY));
+        this.send = (msg) => decoratee.send(this.defaultSerializer(msg));
+        this.close = () => decoratee.close();
+    }
+}
+exports.WsJsonEncoder = WsJsonEncoder;

package/dist/transports/ws.d.ts

@@ -8,16 +8,6 @@ export interface WsDuplexTransportOptions {
      * (e.g. Authorization, User-Agent).
      */
     headers?: Record<string, string>;
-    /**
-     * Serialise an outbound message to a string or Buffer.
-     * Defaults to `JSON.stringify`.
-     */
-    serialise?: (msg: unknown) => string;
-    /**
-     * Deserialise an inbound raw payload to a message object.
-     * Defaults to `JSON.parse`.
-     */
-    deserialise?: (raw: string) => unknown;
     /** Initial reconnect delay in ms (default 1 000). */
     reconnectDelay?: number;
     /** Maximum reconnect delay in ms (default 30 000). */
@@ -25,10 +15,10 @@ export interface WsDuplexTransportOptions {
     /** When false, no automatic reconnect is attempted (default true). */
     autoReconnect?: boolean;
 }
-export declare class WsDuplexTransport<TIn, TOut> implements DuplexTransport<TIn, TOut> {
+export declare class WsDuplexTransport implements DuplexTransport<string, string> {
     private readonly opts;
     readonly connected$: Observable<boolean>;
-    readonly messages$: Observable<TIn>;
+    readonly messages$: Observable<string>;
     readonly errors$: Observable<Error>;
     private readonly _connected$;
     private readonly _messages$;
@@ -40,12 +30,8 @@ export declare class WsDuplexTransport<TIn, TOut> implements DuplexTransport<TIn
     private readonly maxDelay;
     private readonly autoReconnect;
     private destroyed;
-    private readonly serialise;
-    private readonly deserialise;
-    private defaultDeserializer;
-    private defaultSerializer;
     constructor(opts: WsDuplexTransportOptions);
-    send(msg: TOut): void;
+    send(msg: string): void;
     close(): void;
     /** Single subscription that drains the outbound queue when connected. */
     private setupSender;

package/dist/transports/ws.js

@@ -14,7 +14,7 @@ const rxjs_1 = require("rxjs");
 /* ---------------------------------------------------------------- */
 class WsDuplexTransport {
     constructor(opts) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c;
         this.opts = opts;
         // ---- internal subjects ----
         this._connected$ = new rxjs_1.BehaviorSubject(false);
@@ -23,28 +23,12 @@ class WsDuplexTransport {
         this.outbound$ = new rxjs_1.Subject();
         this.destroy$ = new rxjs_1.Subject();
         this.destroyed = false;
-        this.defaultDeserializer = (raw) => {
-            const env = JSON.parse(raw);
-            return {
-                kind: env.event,
-                ...env.data,
-            };
-        };
-        this.defaultSerializer = (msg) => {
-            if (typeof msg === 'object' && 'kind' in (msg || {})) {
-                const { kind, ...data } = msg;
-                return JSON.stringify({ event: kind, data });
-            }
-            return JSON.stringify(msg);
-        };
         this.connected$ = this._connected$.asObservable();
         this.messages$ = this._messages$.asObservable();
         this.errors$ = this._errors$.asObservable();
         this.reconnectDelay = (_a = opts.reconnectDelay) !== null && _a !== void 0 ? _a : 1000;
         this.maxDelay = (_b = opts.maxReconnectDelay) !== null && _b !== void 0 ? _b : 30000;
         this.autoReconnect = (_c = opts.autoReconnect) !== null && _c !== void 0 ? _c : true;
-        this.serialise = ((_d = opts.serialise) !== null && _d !== void 0 ? _d : this.defaultSerializer);
-        this.deserialise = ((_e = opts.deserialise) !== null && _e !== void 0 ? _e : this.defaultDeserializer);
         this.connect();
         this.setupSender();
     }
@@ -52,7 +36,7 @@ class WsDuplexTransport {
     /* Public API                                                     */
     /* -------------------------------------------------------------- */
     send(msg) {
-        this.outbound$.next(this.serialise(msg));
+        this.outbound$.next(msg);
     }
     close() {
         var _a;
@@ -89,7 +73,7 @@ class WsDuplexTransport {
         });
         this.ws.on('message', (data) => {
             try {
-                const msg = this.deserialise(data.toString());
+                const msg = data.toString();
                 this._messages$.next(msg);
             }
             catch (err) {

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "git+https://github.com/Linc-Security-Systems/aware-essentials.git"
   },
-  "version": "2.0.74",
+  "version": "2.0.76",
   "description": "SDK for building Agent implementations that speak the agent protocol.",
   "author": "Yaser Awajan",
   "license": "MIT",
@@ -26,17 +26,17 @@
   "scripts": {
     "build": "tsc -p tsconfig.json  && cp package.json dist/",
     "prepublishOnly": "yarn build",
-    "test": "echo \"add unit tests here\"",
+    "test": "vitest run",
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "lint:fix": "yarn lint --fix"
   },
   "peerDependencies": {
-    "@awarevue/api-types": "2.0.74",
+    "@awarevue/api-types": "2.0.76",
     "rxjs": "^7.8.2",
     "ws": "^8"
   },
   "devDependencies": {
-    "@awarevue/api-types": "2.0.74",
+    "@awarevue/api-types": "2.0.76",
     "@types/node": "^20.12.7",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.31.1",
@@ -46,6 +46,7 @@
     "eslint-plugin-import": "^2.31.0",
     "rxjs": "7.8.2",
     "typescript": "^5.8.3",
+    "vitest": "^4.1.4",
     "ws": "^8",
     "zod": "3.25.76"
   },