@agentionai/agents 0.3.0-beta

package/dist/viz/VizReporter.js

@@ -0,0 +1,595 @@
+"use strict";
+/**
+ * VizReporter - Singleton for sending visualization events to @agention/viz.
+ *
+ * This class manages WebSocket connections and event reporting for agent monitoring.
+ * Events are queued when disconnected and flushed on reconnection.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vizReporter = exports.VizReporter = void 0;
+const events_1 = require("events");
+const VizConfig_1 = require("./VizConfig");
+// WebSocket implementation - supports both browser and Node.js
+// In Node.js, requires 'ws' package to be installed
+let WebSocketImpl = null;
+let wsModuleLoaded = false;
+async function loadWebSocket() {
+    if (wsModuleLoaded)
+        return WebSocketImpl;
+    wsModuleLoaded = true;
+    // Check for browser WebSocket
+    if (typeof WebSocket !== "undefined") {
+        WebSocketImpl = WebSocket;
+        return WebSocketImpl;
+    }
+    // Try to load Node.js ws module
+    try {
+        // Use dynamic import with a variable to avoid TypeScript resolution
+        const moduleName = "ws";
+        const wsModule = await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s)));
+        WebSocketImpl = wsModule.default || wsModule;
+        return WebSocketImpl;
+    }
+    catch {
+        // ws module not installed - visualization will be disabled
+        return null;
+    }
+}
+/**
+ * Generate a unique ID for events
+ */
+function generateId() {
+    return `${Date.now().toString(36)}-${Math.random()
+        .toString(36)
+        .slice(2, 11)}`;
+}
+/**
+ * Truncate a string to a maximum length
+ */
+function truncate(str, maxLength = 200) {
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength) + "...";
+}
+/**
+ * Safely stringify an object for summaries
+ */
+function summarize(obj, maxLength = 200) {
+    try {
+        const str = typeof obj === "string" ? obj : JSON.stringify(obj);
+        return truncate(str, maxLength);
+    }
+    catch {
+        return "[Unable to serialize]";
+    }
+}
+class VizReporter extends events_1.EventEmitter {
+    constructor() {
+        super();
+        this.ws = null;
+        this.queue = [];
+        this.currentSessionId = null;
+        this.currentPipelineId = null;
+        this.eventStack = [];
+        this.eventTimings = new Map();
+        this.connecting = false;
+        this.reconnectTimer = null;
+        this.initWebSocket();
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!VizReporter.instance) {
+            VizReporter.instance = new VizReporter();
+        }
+        return VizReporter.instance;
+    }
+    /**
+     * Reset the singleton (for testing)
+     */
+    static resetInstance() {
+        if (VizReporter.instance) {
+            VizReporter.instance.disconnect();
+            VizReporter.instance = null;
+        }
+    }
+    /**
+     * Initialize WebSocket connection
+     */
+    async initWebSocket() {
+        if (!VizConfig_1.vizConfig.isEnabled())
+            return;
+        // Load WebSocket implementation
+        const ws = await loadWebSocket();
+        if (!ws) {
+            // WebSocket not available - this is fine, visualization just won't work
+            return;
+        }
+        this.tryConnect();
+    }
+    /**
+     * Attempt to connect to the visualization server
+     */
+    async tryConnect() {
+        if (!VizConfig_1.vizConfig.isEnabled() || this.connecting || this.ws)
+            return;
+        // Ensure WebSocket is loaded
+        const WS = await loadWebSocket();
+        if (!WS)
+            return;
+        this.connecting = true;
+        try {
+            const ws = new WS(VizConfig_1.vizConfig.getUrl());
+            ws.onopen = () => {
+                this.ws = ws;
+                this.connecting = false;
+                this.emit("connected");
+                this.flushQueue();
+            };
+            ws.onclose = () => {
+                this.ws = null;
+                this.connecting = false;
+                this.emit("disconnected");
+                this.scheduleReconnect();
+            };
+            ws.onerror = () => {
+                ws.close();
+            };
+        }
+        catch {
+            this.connecting = false;
+            this.scheduleReconnect();
+        }
+    }
+    /**
+     * Schedule a reconnection attempt
+     */
+    scheduleReconnect() {
+        if (!VizConfig_1.vizConfig.get().reconnect)
+            return;
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.tryConnect();
+        }, VizConfig_1.vizConfig.get().reconnectInterval);
+    }
+    /**
+     * Flush queued events
+     */
+    flushQueue() {
+        if (!this.ws || this.ws.readyState !== 1)
+            return; // 1 = OPEN
+        while (this.queue.length > 0) {
+            const event = this.queue.shift();
+            if (event) {
+                this.ws.send(JSON.stringify(event));
+            }
+        }
+    }
+    /**
+     * Disconnect from the visualization server
+     */
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.connecting = false;
+    }
+    /**
+     * Check if connected to the visualization server
+     */
+    isConnected() {
+        return this.ws !== null && this.ws.readyState === 1; // 1 = OPEN
+    }
+    /**
+     * Send an event to the visualization server
+     */
+    send(event) {
+        if (!VizConfig_1.vizConfig.isEnabled())
+            return;
+        const fullEvent = {
+            eventId: event.eventId || generateId(),
+            sessionId: event.sessionId || this.currentSessionId || "default",
+            pipelineId: event.pipelineId || this.currentPipelineId || undefined,
+            parentEventId: event.parentEventId ||
+                (this.eventStack.length > 0
+                    ? this.eventStack[this.eventStack.length - 1]
+                    : undefined),
+            timestamp: event.timestamp || Date.now(),
+            durationMs: event.durationMs,
+            eventType: event.eventType,
+            source: event.source,
+            payload: event.payload,
+        };
+        if (this.ws && this.ws.readyState === 1) {
+            // 1 = OPEN
+            this.ws.send(JSON.stringify(fullEvent));
+        }
+        else {
+            // Queue the event
+            if (this.queue.length < VizConfig_1.vizConfig.get().maxQueueSize) {
+                this.queue.push(fullEvent);
+            }
+            // Try to connect if not already
+            this.tryConnect();
+        }
+    }
+    // ============================================
+    // Session Management
+    // ============================================
+    /**
+     * Start a new session
+     */
+    startSession(name) {
+        const sessionId = generateId();
+        this.currentSessionId = sessionId;
+        const sessionName = name || VizConfig_1.vizConfig.getSessionName() || undefined;
+        this.send({
+            eventId: sessionId,
+            sessionId,
+            eventType: "session.start",
+            source: {
+                agentId: "system",
+                agentName: "System",
+                model: "n/a",
+                vendor: "anthropic",
+            },
+            payload: { name: sessionName },
+        });
+        return sessionId;
+    }
+    /**
+     * End the current session
+     */
+    endSession(reason = "completed") {
+        if (!this.currentSessionId)
+            return;
+        this.send({
+            sessionId: this.currentSessionId,
+            eventType: "session.end",
+            source: {
+                agentId: "system",
+                agentName: "System",
+                model: "n/a",
+                vendor: "anthropic",
+            },
+            payload: { reason },
+        });
+        this.currentSessionId = null;
+    }
+    /**
+     * Get or create a session ID
+     */
+    getSessionId() {
+        if (!this.currentSessionId) {
+            return this.startSession();
+        }
+        return this.currentSessionId;
+    }
+    /**
+     * Set the current session ID (for external session management)
+     */
+    setSessionId(sessionId) {
+        this.currentSessionId = sessionId;
+    }
+    // ============================================
+    // Pipeline Management
+    // ============================================
+    /**
+     * Start a pipeline execution
+     */
+    pipelineStart(name, structure, input, source) {
+        const eventId = generateId();
+        this.currentPipelineId = eventId;
+        this.eventStack.push(eventId);
+        this.eventTimings.set(eventId, { startTime: Date.now(), source });
+        this.send({
+            eventId,
+            pipelineId: eventId,
+            eventType: "pipeline.start",
+            source,
+            payload: {
+                pipelineName: name,
+                nodeType: "pipeline",
+                structure,
+                inputPreview: truncate(input),
+            },
+        });
+        return eventId;
+    }
+    /**
+     * End a pipeline execution
+     */
+    pipelineEnd(eventId, success, totalTokens, nodeCount, output, error) {
+        const timing = this.eventTimings.get(eventId);
+        const durationMs = timing ? Date.now() - timing.startTime : undefined;
+        this.send({
+            eventId,
+            pipelineId: eventId,
+            eventType: "pipeline.end",
+            durationMs,
+            source: timing?.source || {
+                agentId: "system",
+                agentName: "System",
+                model: "n/a",
+                vendor: "anthropic",
+            },
+            payload: {
+                success,
+                totalTokens,
+                nodeCount,
+                outputPreview: output ? truncate(output) : undefined,
+                error,
+            },
+        });
+        this.eventTimings.delete(eventId);
+        this.popEventStack(eventId);
+        if (this.currentPipelineId === eventId) {
+            this.currentPipelineId = null;
+        }
+    }
+    // ============================================
+    // Executor Management
+    // ============================================
+    /**
+     * Start an executor (sequential, parallel, map, voting, router)
+     */
+    executorStart(name, type, childCount, input, source) {
+        const eventId = generateId();
+        this.eventStack.push(eventId);
+        this.eventTimings.set(eventId, { startTime: Date.now(), source });
+        this.send({
+            eventId,
+            eventType: "executor.start",
+            source,
+            payload: {
+                executorName: name,
+                executorType: type,
+                childCount,
+                inputPreview: truncate(input),
+            },
+        });
+        return eventId;
+    }
+    /**
+     * End an executor
+     */
+    executorEnd(eventId, success, totalTokens, output, error) {
+        const timing = this.eventTimings.get(eventId);
+        const durationMs = timing ? Date.now() - timing.startTime : undefined;
+        this.send({
+            eventId,
+            eventType: "executor.end",
+            durationMs,
+            source: timing?.source || {
+                agentId: "system",
+                agentName: "System",
+                model: "n/a",
+                vendor: "anthropic",
+            },
+            payload: {
+                success,
+                totalTokens,
+                outputPreview: output ? truncate(output) : undefined,
+                error,
+            },
+        });
+        this.eventTimings.delete(eventId);
+        this.popEventStack(eventId);
+    }
+    // ============================================
+    // Agent Events
+    // ============================================
+    /**
+     * Report agent execution start
+     */
+    agentStart(agentId, agentName, model, vendor, input) {
+        const eventId = generateId();
+        const source = { agentId, agentName, model, vendor };
+        this.eventStack.push(eventId);
+        this.eventTimings.set(eventId, { startTime: Date.now(), source });
+        this.send({
+            eventId,
+            eventType: "agent.start",
+            source,
+            payload: {
+                inputPreview: truncate(input),
+            },
+        });
+        return eventId;
+    }
+    /**
+     * Report agent execution complete
+     */
+    agentComplete(eventId, tokens, stopReason, hasToolCalls, toolCallCount, output) {
+        const timing = this.eventTimings.get(eventId);
+        const durationMs = timing ? Date.now() - timing.startTime : undefined;
+        this.send({
+            eventId,
+            eventType: "agent.complete",
+            durationMs,
+            source: timing?.source || {
+                agentId: "unknown",
+                agentName: "Unknown",
+                model: "unknown",
+                vendor: "anthropic",
+            },
+            payload: {
+                tokens,
+                stopReason,
+                hasToolCalls,
+                toolCallCount,
+                outputPreview: truncate(output),
+            },
+        });
+        this.eventTimings.delete(eventId);
+        this.popEventStack(eventId);
+    }
+    /**
+     * Report agent execution error
+     */
+    agentError(eventId, errorType, errorMessage, retryable = false) {
+        const timing = this.eventTimings.get(eventId);
+        const durationMs = timing ? Date.now() - timing.startTime : undefined;
+        this.send({
+            eventId,
+            eventType: "agent.error",
+            durationMs,
+            source: timing?.source || {
+                agentId: "unknown",
+                agentName: "Unknown",
+                model: "unknown",
+                vendor: "anthropic",
+            },
+            payload: {
+                errorType,
+                errorMessage: truncate(errorMessage, 500),
+                retryable,
+            },
+        });
+        this.eventTimings.delete(eventId);
+        this.popEventStack(eventId);
+    }
+    // ============================================
+    // Tool Events
+    // ============================================
+    /**
+     * Report tool execution start
+     */
+    toolStart(toolName, toolId, input, agentSource) {
+        const eventId = generateId();
+        this.eventTimings.set(eventId, {
+            startTime: Date.now(),
+            source: agentSource,
+        });
+        this.send({
+            eventId,
+            eventType: "tool.start",
+            source: agentSource,
+            payload: {
+                toolName,
+                toolId,
+                inputSummary: summarize(input),
+            },
+        });
+        return eventId;
+    }
+    /**
+     * Report tool execution complete
+     */
+    toolComplete(eventId, toolName, toolId, success, result) {
+        const timing = this.eventTimings.get(eventId);
+        const durationMs = timing ? Date.now() - timing.startTime : undefined;
+        this.send({
+            eventId,
+            eventType: "tool.complete",
+            durationMs,
+            source: timing?.source || {
+                agentId: "unknown",
+                agentName: "Unknown",
+                model: "unknown",
+                vendor: "anthropic",
+            },
+            payload: {
+                toolName,
+                toolId,
+                success,
+                resultSummary: summarize(result),
+            },
+        });
+        this.eventTimings.delete(eventId);
+    }
+    /**
+     * Report tool execution error
+     */
+    toolError(eventId, toolName, toolId, errorMessage) {
+        const timing = this.eventTimings.get(eventId);
+        const durationMs = timing ? Date.now() - timing.startTime : undefined;
+        this.send({
+            eventId,
+            eventType: "tool.error",
+            durationMs,
+            source: timing?.source || {
+                agentId: "unknown",
+                agentName: "Unknown",
+                model: "unknown",
+                vendor: "anthropic",
+            },
+            payload: {
+                toolName,
+                toolId,
+                errorMessage: truncate(errorMessage, 500),
+            },
+        });
+        this.eventTimings.delete(eventId);
+    }
+    // ============================================
+    // Helper Methods
+    // ============================================
+    /**
+     * Pop an event from the stack
+     */
+    popEventStack(eventId) {
+        const index = this.eventStack.lastIndexOf(eventId);
+        if (index !== -1) {
+            this.eventStack.splice(index, 1);
+        }
+    }
+    /**
+     * Get current event stack depth
+     */
+    getStackDepth() {
+        return this.eventStack.length;
+    }
+    /**
+     * Get queued event count
+     */
+    getQueueSize() {
+        return this.queue.length;
+    }
+}
+exports.VizReporter = VizReporter;
+VizReporter.instance = null;
+/** Global VizReporter instance */
+exports.vizReporter = VizReporter.getInstance();
+//# sourceMappingURL=VizReporter.js.map

package/dist/viz/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Visualization module for agent monitoring.
+ *
+ * This module provides tools for sending agent execution events
+ * to a visualization server (@agention/viz).
+ *
+ * @example
+ * ```typescript
+ * import { vizConfig, vizReporter } from 'agention-lib';
+ *
+ * // Enable visualization programmatically
+ * vizConfig.set({ enabled: true, url: 'ws://localhost:4242/ws/agent' });
+ *
+ * // Or use environment variables:
+ * // AGENTION_VIZ_ENABLED=true
+ * // AGENTION_VIZ_URL=ws://localhost:4242/ws/agent
+ *
+ * // Start a session
+ * vizReporter.startSession('My Test Session');
+ *
+ * // Agent events are automatically reported when visualization is enabled
+ * const response = await agent.execute('Hello!');
+ *
+ * // End the session
+ * vizReporter.endSession('completed');
+ * ```
+ */
+export { vizConfig, type VizConfigOptions } from "./VizConfig";
+export { vizReporter, VizReporter } from "./VizReporter";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/viz/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Visualization module for agent monitoring.
+ *
+ * This module provides tools for sending agent execution events
+ * to a visualization server (@agention/viz).
+ *
+ * @example
+ * ```typescript
+ * import { vizConfig, vizReporter } from 'agention-lib';
+ *
+ * // Enable visualization programmatically
+ * vizConfig.set({ enabled: true, url: 'ws://localhost:4242/ws/agent' });
+ *
+ * // Or use environment variables:
+ * // AGENTION_VIZ_ENABLED=true
+ * // AGENTION_VIZ_URL=ws://localhost:4242/ws/agent
+ *
+ * // Start a session
+ * vizReporter.startSession('My Test Session');
+ *
+ * // Agent events are automatically reported when visualization is enabled
+ * const response = await agent.execute('Hello!');
+ *
+ * // End the session
+ * vizReporter.endSession('completed');
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VizReporter = exports.vizReporter = exports.vizConfig = void 0;
+var VizConfig_1 = require("./VizConfig");
+Object.defineProperty(exports, "vizConfig", { enumerable: true, get: function () { return VizConfig_1.vizConfig; } });
+var VizReporter_1 = require("./VizReporter");
+Object.defineProperty(exports, "vizReporter", { enumerable: true, get: function () { return VizReporter_1.vizReporter; } });
+Object.defineProperty(exports, "VizReporter", { enumerable: true, get: function () { return VizReporter_1.VizReporter; } });
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map