agent-room 0.2.0

package/dist/core/connection-manager.js

@@ -0,0 +1,205 @@
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import { WsAdapter } from "../protocols/ws-adapter.js";
+import { SseAdapter } from "../protocols/sse-adapter.js";
+import { Logger } from "./logger.js";
+const log = Logger.create("connection-mgr");
+/**
+ * Manages multiple concurrent stream connections, each identified by a channelId.
+ * Delegates actual protocol handling to WsAdapter / SseAdapter.
+ */
+export class ConnectionManager extends EventEmitter {
+    _connections = new Map();
+    // ─── Public API ────────────────────────────────────────────────────
+    /**
+     * Open a new stream connection.
+     * Returns the channelId (auto-generated if not provided).
+     */
+    async connect(url, protocol, channelId, options) {
+        const id = channelId ?? randomUUID().slice(0, 8);
+        if (this._connections.has(id)) {
+            throw new Error(`Channel "${id}" already exists. Disconnect first or use a different ID.`);
+        }
+        const done = log.time("connect", { channelId: id, url, protocol });
+        const adapter = this._createAdapter(protocol);
+        const conn = {
+            channelId: id,
+            url,
+            protocol,
+            adapter,
+            messageCount: 0,
+        };
+        // Wire adapter events before connecting
+        adapter.on("connected", () => {
+            conn.connectedAt = new Date().toISOString();
+            this._emitStateChange(conn);
+        });
+        adapter.on("message", (data) => {
+            conn.messageCount++;
+            Logger.metrics.increment("messages.received");
+            this.emit("message", id, data);
+            this._emitStateChange(conn);
+        });
+        adapter.on("disconnected", (reason) => {
+            log.warn("channel disconnected", { channelId: id, reason });
+            Logger.metrics.increment("connections.disconnected");
+            this._emitStateChange(conn);
+        });
+        adapter.on("reconnecting", (attempt) => {
+            log.info("channel reconnecting", { channelId: id, attempt });
+            Logger.metrics.increment("connections.reconnect_attempts");
+            this._emitStateChange(conn);
+        });
+        adapter.on("error", (err) => {
+            log.error("channel error", { channelId: id }, err);
+            Logger.metrics.increment("errors.connection");
+            this._emitStateChange(conn);
+        });
+        this._connections.set(id, conn);
+        try {
+            await adapter.connect(url, options);
+            done();
+            Logger.metrics.increment("connections.opened");
+        }
+        catch (err) {
+            // If initial connect fails, clean up
+            this._connections.delete(id);
+            log.error("connect failed", { channelId: id, url, protocol }, err);
+            Logger.metrics.increment("errors.connect_failed");
+            throw err;
+        }
+        return id;
+    }
+    /**
+     * Disconnect a channel.
+     */
+    async disconnect(channelId) {
+        const conn = this._connections.get(channelId);
+        if (!conn) {
+            throw new Error(`Channel "${channelId}" not found`);
+        }
+        log.debug("disconnecting channel", { channelId });
+        await conn.adapter.disconnect();
+        this._connections.delete(channelId);
+        Logger.metrics.increment("connections.closed");
+        log.info("channel disconnected (intentional)", { channelId });
+    }
+    /**
+     * Disconnect all channels.
+     */
+    async disconnectAll() {
+        const ids = [...this._connections.keys()];
+        await Promise.allSettled(ids.map((id) => this.disconnect(id)));
+    }
+    /**
+     * Send data through a specific channel.
+     */
+    async send(channelId, data) {
+        const conn = this._connections.get(channelId);
+        if (!conn) {
+            throw new Error(`Channel "${channelId}" not found`);
+        }
+        const done = log.time("send", { channelId });
+        try {
+            await conn.adapter.send(data);
+            done();
+            Logger.metrics.increment("messages.sent");
+        }
+        catch (err) {
+            log.error("send failed", { channelId }, err);
+            Logger.metrics.increment("errors.send_failed");
+            throw err;
+        }
+    }
+    /**
+     * Get info for a specific channel.
+     */
+    getConnectionInfo(channelId) {
+        const conn = this._connections.get(channelId);
+        if (!conn)
+            return undefined;
+        return this._toInfo(conn);
+    }
+    /**
+     * List all active connections.
+     */
+    listConnections() {
+        return [...this._connections.values()].map((c) => this._toInfo(c));
+    }
+    /**
+     * Check if a channel exists.
+     */
+    has(channelId) {
+        return this._connections.has(channelId);
+    }
+    /**
+     * Wait for the next message on a channel, with optional substring filter.
+     * Returns a Promise that resolves with the raw message data, or rejects on timeout.
+     *
+     * @param channelId  The channel to listen on
+     * @param timeoutMs  Max time to wait (default 30000ms)
+     * @param filter     Optional substring — only messages containing this string will resolve the promise
+     * @returns          The raw message string that matched
+     */
+    waitForMessage(channelId, timeoutMs = 30_000, filter) {
+        if (!this._connections.has(channelId)) {
+            return Promise.reject(new Error(`Channel "${channelId}" not found`));
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const onMessage = (id, data) => {
+                if (settled)
+                    return;
+                if (id !== channelId)
+                    return;
+                if (filter && !data.includes(filter))
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.removeListener("message", onMessage);
+                resolve({ data, timedOut: false });
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.removeListener("message", onMessage);
+                resolve({ data: null, timedOut: true });
+            }, timeoutMs);
+            // Use the base EventEmitter 'on' to avoid typed overload issues
+            super.on("message", onMessage);
+        });
+    }
+    // ─── Internal ────────────────────────────────────────────────────────
+    _createAdapter(protocol) {
+        switch (protocol) {
+            case "ws":
+                return new WsAdapter();
+            case "sse":
+                return new SseAdapter();
+            default:
+                throw new Error(`Unsupported protocol: ${protocol}`);
+        }
+    }
+    _toInfo(conn) {
+        return {
+            channelId: conn.channelId,
+            url: conn.url,
+            protocol: conn.protocol,
+            state: conn.adapter.state,
+            connectedAt: conn.connectedAt,
+            messageCount: conn.messageCount,
+        };
+    }
+    _emitStateChange(conn) {
+        this.emit("stateChange", conn.channelId, this._toInfo(conn));
+    }
+    // Typed event helpers
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+}
+//# sourceMappingURL=connection-manager.js.map

package/dist/core/connection-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-manager.js","sourceRoot":"","sources":["../../src/core/connection-manager.ts"],"names":[],"mappings":"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"}

package/dist/core/logger.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Structured Logger — lightweight, zero-dependency logging for AgentRoom.
+ *
+ * Features:
+ *   - Log levels: debug, info, warn, error
+ *   - Structured context (key-value pairs attached to every log line)
+ *   - Performance timing via `time()` / `timeEnd()` (tracks duration in ms)
+ *   - Error tracking with stack traces
+ *   - Metrics: counters and histograms for aggregate stats
+ *   - Outputs to stderr (stdout reserved for MCP protocol)
+ *   - Configurable via LOG_LEVEL env var (default: "info")
+ *
+ * Usage:
+ *   const log = Logger.create("ws-adapter");
+ *   log.info("connected", { url, channelId });
+ *   log.error("connection failed", { url, err });
+ *
+ *   const done = log.time("connect");
+ *   await doConnect();
+ *   done();  // logs: [ws-adapter] connect completed in 42ms
+ *
+ *   Logger.metrics.increment("messages.received");
+ *   Logger.metrics.record("connect.duration_ms", 42);
+ *   Logger.metrics.snapshot(); // returns all metrics
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    component: string;
+    message: string;
+    context?: Record<string, unknown>;
+    error?: {
+        message: string;
+        stack?: string;
+    };
+    duration_ms?: number;
+}
+export declare class MetricsCollector {
+    private _counters;
+    private _histograms;
+    private _startedAt;
+    /** Increment a counter by 1 (or a custom amount). */
+    increment(name: string, amount?: number): void;
+    /** Record a numeric sample into a histogram (e.g. latency, duration). */
+    record(name: string, value: number): void;
+    /** Get current value of a counter. */
+    getCounter(name: string): number;
+    /** Get summary statistics for a histogram. */
+    getHistogram(name: string): {
+        count: number;
+        min: number;
+        max: number;
+        avg: number;
+        p50: number;
+        p95: number;
+        p99: number;
+    } | null;
+    /** Return a full snapshot of all metrics. */
+    snapshot(): {
+        uptime_ms: number;
+        counters: Record<string, number>;
+        histograms: Record<string, ReturnType<MetricsCollector["getHistogram"]>>;
+    };
+    /** Reset all metrics. */
+    reset(): void;
+}
+export declare class Logger {
+    /** Shared metrics collector (singleton). */
+    static readonly metrics: MetricsCollector;
+    /** Current global log level. Override with LOG_LEVEL env var. */
+    private static _level;
+    /** JSON output mode (LOG_FORMAT=json). Default: human-readable. */
+    private static _jsonMode;
+    private _component;
+    private constructor();
+    /** Create a logger for a specific component. */
+    static create(component: string): Logger;
+    /** Set the global log level at runtime. */
+    static setLevel(level: LogLevel): void;
+    /** Get the global log level. */
+    static getLevel(): LogLevel;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>, err?: Error | unknown): void;
+    /**
+     * Start a performance timer. Returns a `done()` function.
+     * When called, `done()` logs the elapsed time and records it in metrics.
+     *
+     * @param operation  Name of the operation (e.g. "ws.connect", "room.join")
+     * @param context    Optional extra context
+     * @returns          A `done(extraContext?)` function
+     */
+    time(operation: string, context?: Record<string, unknown>): (extraContext?: Record<string, unknown>) => number;
+    private _log;
+    private _formatHuman;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}

package/dist/core/logger.js

@@ -0,0 +1,204 @@
+/**
+ * Structured Logger — lightweight, zero-dependency logging for AgentRoom.
+ *
+ * Features:
+ *   - Log levels: debug, info, warn, error
+ *   - Structured context (key-value pairs attached to every log line)
+ *   - Performance timing via `time()` / `timeEnd()` (tracks duration in ms)
+ *   - Error tracking with stack traces
+ *   - Metrics: counters and histograms for aggregate stats
+ *   - Outputs to stderr (stdout reserved for MCP protocol)
+ *   - Configurable via LOG_LEVEL env var (default: "info")
+ *
+ * Usage:
+ *   const log = Logger.create("ws-adapter");
+ *   log.info("connected", { url, channelId });
+ *   log.error("connection failed", { url, err });
+ *
+ *   const done = log.time("connect");
+ *   await doConnect();
+ *   done();  // logs: [ws-adapter] connect completed in 42ms
+ *
+ *   Logger.metrics.increment("messages.received");
+ *   Logger.metrics.record("connect.duration_ms", 42);
+ *   Logger.metrics.snapshot(); // returns all metrics
+ */
+// ─── Level Ordering ───────────────────────────────────────────────────
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+// ─── Metrics Collector ────────────────────────────────────────────────
+export class MetricsCollector {
+    _counters = new Map();
+    _histograms = new Map();
+    _startedAt = Date.now();
+    /** Increment a counter by 1 (or a custom amount). */
+    increment(name, amount = 1) {
+        this._counters.set(name, (this._counters.get(name) ?? 0) + amount);
+    }
+    /** Record a numeric sample into a histogram (e.g. latency, duration). */
+    record(name, value) {
+        let samples = this._histograms.get(name);
+        if (!samples) {
+            samples = [];
+            this._histograms.set(name, samples);
+        }
+        samples.push(value);
+        // Keep last 1000 samples to bound memory
+        if (samples.length > 1000) {
+            samples.splice(0, samples.length - 1000);
+        }
+    }
+    /** Get current value of a counter. */
+    getCounter(name) {
+        return this._counters.get(name) ?? 0;
+    }
+    /** Get summary statistics for a histogram. */
+    getHistogram(name) {
+        const samples = this._histograms.get(name);
+        if (!samples || samples.length === 0)
+            return null;
+        const sorted = [...samples].sort((a, b) => a - b);
+        const count = sorted.length;
+        const sum = sorted.reduce((a, b) => a + b, 0);
+        return {
+            count,
+            min: sorted[0],
+            max: sorted[count - 1],
+            avg: Math.round((sum / count) * 100) / 100,
+            p50: sorted[Math.floor(count * 0.5)],
+            p95: sorted[Math.floor(count * 0.95)],
+            p99: sorted[Math.floor(count * 0.99)],
+        };
+    }
+    /** Return a full snapshot of all metrics. */
+    snapshot() {
+        const counters = {};
+        for (const [k, v] of this._counters)
+            counters[k] = v;
+        const histograms = {};
+        for (const [k] of this._histograms)
+            histograms[k] = this.getHistogram(k);
+        return {
+            uptime_ms: Date.now() - this._startedAt,
+            counters,
+            histograms,
+        };
+    }
+    /** Reset all metrics. */
+    reset() {
+        this._counters.clear();
+        this._histograms.clear();
+        this._startedAt = Date.now();
+    }
+}
+// ─── Logger ───────────────────────────────────────────────────────────
+export class Logger {
+    /** Shared metrics collector (singleton). */
+    static metrics = new MetricsCollector();
+    /** Current global log level. Override with LOG_LEVEL env var. */
+    static _level = process.env.LOG_LEVEL ?? "info";
+    /** JSON output mode (LOG_FORMAT=json). Default: human-readable. */
+    static _jsonMode = process.env.LOG_FORMAT === "json";
+    _component;
+    constructor(component) {
+        this._component = component;
+    }
+    /** Create a logger for a specific component. */
+    static create(component) {
+        return new Logger(component);
+    }
+    /** Set the global log level at runtime. */
+    static setLevel(level) {
+        Logger._level = level;
+    }
+    /** Get the global log level. */
+    static getLevel() {
+        return Logger._level;
+    }
+    // ─── Log Methods ──────────────────────────────────────────────────
+    debug(message, context) {
+        this._log("debug", message, context);
+    }
+    info(message, context) {
+        this._log("info", message, context);
+    }
+    warn(message, context) {
+        this._log("warn", message, context);
+    }
+    error(message, context, err) {
+        const entry = {};
+        if (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            entry.error = { message: e.message, stack: e.stack };
+        }
+        this._log("error", message, context, entry);
+    }
+    // ─── Performance Timing ───────────────────────────────────────────
+    /**
+     * Start a performance timer. Returns a `done()` function.
+     * When called, `done()` logs the elapsed time and records it in metrics.
+     *
+     * @param operation  Name of the operation (e.g. "ws.connect", "room.join")
+     * @param context    Optional extra context
+     * @returns          A `done(extraContext?)` function
+     */
+    time(operation, context) {
+        const start = performance.now();
+        return (extraContext) => {
+            const duration = Math.round((performance.now() - start) * 100) / 100;
+            const mergedContext = { ...context, ...extraContext };
+            this._log("info", `${operation} completed`, mergedContext, { duration_ms: duration });
+            // Record in metrics histogram
+            Logger.metrics.record(`${operation}.duration_ms`, duration);
+            return duration;
+        };
+    }
+    // ─── Internal ─────────────────────────────────────────────────────
+    _log(level, message, context, extra) {
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[Logger._level])
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            component: this._component,
+            message,
+            ...extra,
+        };
+        if (context && Object.keys(context).length > 0) {
+            entry.context = context;
+        }
+        if (Logger._jsonMode) {
+            process.stderr.write(JSON.stringify(entry) + "\n");
+        }
+        else {
+            process.stderr.write(this._formatHuman(entry) + "\n");
+        }
+    }
+    _formatHuman(entry) {
+        const ts = entry.timestamp.slice(11, 23); // HH:mm:ss.SSS
+        const lvl = entry.level.toUpperCase().padEnd(5);
+        const comp = entry.component;
+        const dur = entry.duration_ms !== undefined ? ` (${entry.duration_ms}ms)` : "";
+        let line = `${ts} ${lvl} [${comp}] ${entry.message}${dur}`;
+        if (entry.context) {
+            const pairs = Object.entries(entry.context)
+                .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+                .join(" ");
+            line += ` | ${pairs}`;
+        }
+        if (entry.error) {
+            line += `\n  ERROR: ${entry.error.message}`;
+            if (entry.error.stack && entry.level === "error") {
+                // Show first 3 stack frames
+                const frames = entry.error.stack.split("\n").slice(1, 4).map((f) => `  ${f.trim()}`).join("\n");
+                line += `\n${frames}`;
+            }
+        }
+        return line;
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}

package/dist/core/message-buffer.d.ts

@@ -0,0 +1,42 @@
+import type { StreamMessage } from "../types.js";
+/**
+ * Sliding-window buffer that stores the most recent N messages per channel.
+ * Automatically parses JSON payloads for structured display.
+ */
+export declare class MessageBuffer {
+    private _buffers;
+    private _maxSize;
+    constructor(maxSize?: number);
+    /**
+     * Add a raw message string to a channel's buffer.
+     * Returns the created StreamMessage.
+     */
+    push(channelId: string, raw: string): StreamMessage;
+    /**
+     * Get the most recent `count` messages for a channel.
+     */
+    getRecent(channelId: string, count?: number): StreamMessage[];
+    /**
+     * Get only the latest message for a channel.
+     */
+    getLatest(channelId: string): StreamMessage | undefined;
+    /**
+     * Get all buffered messages for a channel.
+     */
+    getAll(channelId: string): StreamMessage[];
+    /**
+     * Clear a channel's buffer.
+     */
+    clear(channelId: string): void;
+    /**
+     * Clear all buffers.
+     */
+    clearAll(): void;
+    /**
+     * Format messages for AI-readable display.
+     * JSON data is pretty-printed; raw strings are shown as-is.
+     */
+    formatForDisplay(messages: StreamMessage[]): string;
+    private _tryParseJson;
+}
+//# sourceMappingURL=message-buffer.d.ts.map

package/dist/core/message-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-buffer.d.ts","sourceRoot":"","sources":["../../src/core/message-buffer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,GAAE,MAAyB;IAI9C;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAwBnD;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAO7D;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAMvD;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE;IAI1C;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;;OAGG;IACH,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM;IAgBnD,OAAO,CAAC,aAAa;CAOtB"}