@symbolica/agentica 0.2.11-rc

package/dist-transformer/client-session-manager/client-session-manager.js

@@ -0,0 +1,966 @@
+import { Usage, makeRole } from '../agentica/common.js';
+import { createLogger, loggingConfig } from '../logging/index.js';
+import { v4 as uuidv4 } from 'uuid';
+async function createWebSocket(url, apiKey, customHeaders) {
+    // Check for Node.js environment and ws package
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        const WS = await import('ws').then((m) => m.default || m);
+        const headers = { ...customHeaders };
+        if (apiKey) {
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
+        return new WS(url, { headers });
+    }
+    // Browser environment - native WebSocket (doesn't support custom headers)
+    // Note: traceparent would need to be sent via query params or other mechanism in browser
+    if (apiKey) {
+        const separator = url.includes('?') ? '&' : '?';
+        const authenticatedUrl = `${url}${separator}bearer=${encodeURIComponent(apiKey)}`;
+        return new WebSocket(authenticatedUrl);
+    }
+    return new WebSocket(url);
+}
+import { registerCleanup } from './at-exit.js';
+import { decodeMessage, encodeMessage, isServerMessage, uint8ArrayToBase64 } from './message-utils.js';
+import { Queue } from './queue.js';
+import { ConnectionError, SDKUnsupportedError, ServerError, WebSocketConnectionError, attemptToParseMultiplexError, enrichError, } from '../errors/index.js';
+import { waitForTracing } from '../index.js';
+import { injectTraceContext } from '../otel-config.js';
+import { CustomLogFW } from '../otel-logging.js';
+import { version } from '../version.js';
+/**
+ * ClientSessionManager - TypeScript equivalent of the Python ClientSessionManager
+ * Maintains identical structure and method signatures
+ */
+export class ClientSessionManager {
+    constructor(config = {}) {
+        this.websocket = null;
+        this.tasks = null;
+        this.sendQueue = null;
+        this.baseHttp = null;
+        this.baseWs = null;
+        this.apiKey = null;
+        this.uidToLogger = new Map();
+        this.isStopped = false;
+        this.isStopping = false;
+        this.sessionSpan = null;
+        // Invocation guard: keeps process alive only during active WebSocket connections
+        this.activeConnectionCount = 0;
+        this.invocationGuard = null;
+        this.logger = createLogger('session-manager');
+        this.idIssuer = () => uuidv4();
+        this.uidIidRecvQueue = new Map();
+        this.uidIidException = new Map();
+        this.matchIid = new Map();
+        this.iidToUid = new Map();
+        this.knownUids = new Set();
+        this.apiKey = config.apiKey ?? null;
+        // Initialize session management
+        this.clientSessionId = uuidv4();
+        // Start session-level span for entire SDK lifetime
+        this.sessionSpan = this.logger.startSpan('sdk.session');
+        this.sessionSpan.setAttribute('sdk.version', version);
+        this.sessionSpan.setAttribute('sdk.session_id', this.clientSessionId);
+        // Initialize OpenTelemetry logging (optional) - sends logs to session manager's collector
+        if (config.enableOtelLogging || loggingConfig.isOtelLoggingEnabled()) {
+            const instanceId = `sdk-${this.idIssuer().slice(0, 8)}`;
+            const logFW = new CustomLogFW('agentica-sdk-typescript', instanceId);
+            logFW.setupLogging();
+            this.logger.info(`OpenTelemetry logging initialized for SDK instance: ${instanceId}`);
+            if (this.sessionSpan) {
+                this.sessionSpan.setAttribute('sdk.instance_id', instanceId);
+            }
+        }
+        // Cleanup registration happens in setEndpoints() when CSM is actually configured
+        this.logger.info(`Initialized ClientSessionManager with session ID: ${this.clientSessionId}`);
+    }
+    /**
+     * Increment active connection count and create guard if needed.
+     * The guard is a ref'd interval that keeps the process alive during active connections.
+     */
+    refConnection() {
+        this.activeConnectionCount++;
+        if (this.activeConnectionCount === 1 && !this.invocationGuard) {
+            // Create a dummy interval that keeps the process alive
+            this.invocationGuard = setInterval(() => { }, 2147483647); // Max safe interval
+        }
+    }
+    /**
+     * Decrement active connection count and clear guard if no more connections.
+     */
+    unrefConnection() {
+        this.activeConnectionCount = Math.max(0, this.activeConnectionCount - 1);
+        if (this.activeConnectionCount === 0 && this.invocationGuard) {
+            clearInterval(this.invocationGuard);
+            this.invocationGuard = null;
+        }
+    }
+    setEndpoints(baseHttp, baseWs) {
+        this.baseHttp = baseHttp;
+        this.baseWs = baseWs;
+        if (this.sessionSpan) {
+            this.sessionSpan.setAttribute('sdk.base_url', baseHttp);
+        }
+        this.logger.debug(`Endpoints set (http=${baseHttp}, ws=${baseWs})`);
+        // Register for cleanup only when first configured
+        registerCleanup(this, () => this.close());
+        // Register session with server
+        this.registerSession().catch((error) => {
+            this.logger.error('Fatal error during session registration:', error);
+            throw error;
+        });
+    }
+    /**
+     * Register this client session with the server.
+     * Throws an error if registration fails.
+     */
+    async registerSession() {
+        await waitForTracing;
+        if (!this.baseHttp) {
+            const error = new ConnectionError('Cannot register session: baseHttp not set');
+            enrichError(error, { sessionId: this.clientSessionId });
+            throw error;
+        }
+        try {
+            const response = await fetch(`${this.baseHttp}/session/register`, {
+                method: 'POST',
+                headers: this.buildHeaders(),
+            });
+            if (response.ok) {
+                this.logger.info(`Session ${this.clientSessionId} registered with server`);
+            }
+            else {
+                const responseText = await response.text().catch(() => 'unknown error');
+                const error = new ConnectionError(`Failed to register session: HTTP ${response.status} - ${responseText}`);
+                enrichError(error, { sessionId: this.clientSessionId });
+                throw error;
+            }
+        }
+        catch (error) {
+            if (error instanceof ConnectionError) {
+                throw error;
+            }
+            const enrichedError = new ConnectionError(`Failed to register session: ${error instanceof Error ? error.message : 'unknown error'}`);
+            enrichError(enrichedError, { sessionId: this.clientSessionId });
+            throw enrichedError;
+        }
+    }
+    /**
+     * Build authentication headers for HTTP requests.
+     */
+    buildHeaders(additionalHeaders) {
+        const headers = additionalHeaders || {};
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        headers['X-Client-Session-ID'] = this.clientSessionId;
+        return headers;
+    }
+    /**
+     * Background task for writing messages to WebSocket - matches Python _ws_background_task_writer
+     */
+    async wsBackgroundTaskWriter(control) {
+        await waitForTracing;
+        const wsLogger = this.logger.withScope('ws-writer');
+        wsLogger.debug('Writer task started');
+        const ws = this.websocket;
+        try {
+            while (!control.shouldStop) {
+                try {
+                    const sendQueue = this.sendQueue;
+                    if (!sendQueue) {
+                        wsLogger.debug('Send queue removed, exiting writer');
+                        break;
+                    }
+                    const msg = await sendQueue.get();
+                    const msgUid = msg.uid;
+                    const msgLogger = msgUid ? (this.uidToLogger.get(msgUid) ?? wsLogger) : wsLogger;
+                    if (ws.readyState !== 1) {
+                        const error = new WebSocketConnectionError(`cannot send as websocket is not open.`);
+                        enrichError(error, { uid: msgUid, sessionId: this.clientSessionId });
+                        throw error;
+                    }
+                    msgLogger.debug(`Sending ${msg.type} message`);
+                    ws.send(encodeMessage(msg));
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message === 'Queue closed') {
+                        wsLogger.debug('Queue closed, exiting writer');
+                        break;
+                    }
+                    throw error;
+                }
+            }
+            wsLogger.debug('Writer task stopped');
+        }
+        catch (error) {
+            wsLogger.error('Writer task failed', error);
+            for (const [matchId, handlers] of this.matchIid.entries()) {
+                handlers.reject(new WebSocketConnectionError(`WebSocket writer failed: ${error.message}`));
+                this.matchIid.delete(matchId);
+            }
+            for (const [_, exceptionMap] of this.uidIidException.entries()) {
+                for (const [_iid, handlers] of exceptionMap.entries()) {
+                    handlers.reject(new WebSocketConnectionError(`WebSocket writer failed: ${error.message}`));
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Background task for reading messages from WebSocket - matches Python _ws_background_task_reader
+     */
+    async wsBackgroundTaskReader(control) {
+        await waitForTracing;
+        const wsLogger = this.logger.withScope('ws-reader');
+        wsLogger.debug('Reader task started');
+        const ws = this.websocket;
+        ws.onmessage = (event) => {
+            if (control.shouldStop)
+                return;
+            let msg_bytes;
+            // Check for Buffer in Node.js environment
+            if (typeof Buffer !== 'undefined' && event.data instanceof Buffer) {
+                msg_bytes = new Uint8Array(event.data);
+            }
+            else if (event.data instanceof ArrayBuffer) {
+                msg_bytes = new Uint8Array(event.data);
+            }
+            else if (event.data instanceof Uint8Array) {
+                msg_bytes = event.data;
+            }
+            else {
+                wsLogger.warn(`Unexpected WebSocket data type: ${typeof event.data}`);
+                return;
+            }
+            let msg;
+            try {
+                msg = decodeMessage(msg_bytes);
+            }
+            catch (error) {
+                wsLogger.warn('Failed to decode message', error);
+                return;
+            }
+            wsLogger.debug(`Received ${msg.type} message (${msg_bytes.length} bytes)`);
+            if (!isServerMessage(msg)) {
+                wsLogger.debug(`Message is not a server message: ${msg.type}`);
+                wsLogger.debugObject('Message', msg);
+                return;
+            }
+            switch (msg.type) {
+                case 'new_iid': {
+                    wsLogger.debug(`New IID message for match_id=${msg.match_id} uid=${msg.uid} iid=${msg.iid}`);
+                    const promise = this.matchIid.get(msg.match_id);
+                    if (promise) {
+                        promise.resolve(msg.iid);
+                        this.matchIid.delete(msg.match_id);
+                        wsLogger.debug(`Matched IID ${msg.iid} for match_id=${msg.match_id}`);
+                    }
+                    break;
+                }
+                case 'data': {
+                    const uid = msg.uid;
+                    const msgLogger = this.uidToLogger.get(uid) ?? wsLogger;
+                    msgLogger.debug(`Data message for iid=${msg.iid} (${msg.data.length} bytes)`);
+                    const recvQueue = this.uidIidRecvQueue.get(uid)?.get(msg.iid);
+                    if (recvQueue) {
+                        recvQueue.put(msg.data);
+                        msgLogger.debug(`Queued data for iid=${msg.iid} (${msg.data.length} bytes)`);
+                    }
+                    break;
+                }
+                case 'invocation': {
+                    const uid = msg.uid;
+                    const msgLogger = this.uidToLogger.get(uid) ?? wsLogger;
+                    msgLogger.debug(`Invocation message: ${msg.event}`);
+                    const recvQueue = this.uidIidRecvQueue.get(uid)?.get(msg.iid);
+                    const exceptionMap = this.uidIidException.get(uid);
+                    if (msg.event === 'ERROR') {
+                        if (exceptionMap && exceptionMap.has(msg.iid)) {
+                            const resolver = exceptionMap.get(msg.iid);
+                            exceptionMap.delete(msg.iid);
+                            resolver.reject(new ServerError(`Error event for iid=${msg.iid}`));
+                        }
+                        if (recvQueue) {
+                            recvQueue.put(new Uint8Array([0]));
+                        }
+                    }
+                    if (msg.event === 'EXIT') {
+                        msgLogger.debug(`Invocation exit for iid=${msg.iid}`);
+                        if (exceptionMap && exceptionMap.has(msg.iid)) {
+                            exceptionMap.delete(msg.iid);
+                        }
+                    }
+                    break;
+                }
+                case 'error': {
+                    const uid = msg.uid;
+                    const msgLogger = uid ? (this.uidToLogger.get(uid) ?? wsLogger) : wsLogger;
+                    msgLogger.debug(`Error message for iid=${msg.iid}`);
+                    const exceptionMap = uid ? this.uidIidException.get(uid) : undefined;
+                    const error = attemptToParseMultiplexError(msg);
+                    if (exceptionMap && exceptionMap.has(msg.iid)) {
+                        const resolver = exceptionMap.get(msg.iid);
+                        exceptionMap.delete(msg.iid);
+                        resolver.reject(error);
+                    }
+                    break;
+                }
+                default: {
+                    wsLogger.debug(`Unknown message: ${msg}`);
+                    break;
+                }
+            }
+        };
+        return new Promise((resolve) => {
+            ws.onclose = (event) => {
+                wsLogger.debug(`WebSocket closed (code=${event.code}, reason=${event.reason || 'none'})`);
+                control.shouldStop = true;
+                for (const [matchId, handlers] of this.matchIid.entries()) {
+                    handlers.reject(new WebSocketConnectionError(`WebSocket closed: ${event.reason || 'Connection closed'}`));
+                    this.matchIid.delete(matchId);
+                }
+                for (const [_, exceptionMap] of this.uidIidException.entries()) {
+                    for (const [_iid, handlers] of exceptionMap.entries()) {
+                        handlers.reject(new WebSocketConnectionError(`WebSocket closed: ${event.reason || 'Connection closed'}`));
+                    }
+                    exceptionMap.clear();
+                }
+                resolve();
+            };
+            ws.onerror = (_error) => {
+                wsLogger.error('WebSocket error');
+                control.shouldStop = true;
+                for (const [matchId, handlers] of this.matchIid.entries()) {
+                    handlers.reject(new WebSocketConnectionError('WebSocket error occurred'));
+                    this.matchIid.delete(matchId);
+                }
+                for (const [_, exceptionMap] of this.uidIidException.entries()) {
+                    for (const [_iid, handlers] of exceptionMap.entries()) {
+                        handlers.reject(new WebSocketConnectionError('WebSocket error occurred'));
+                    }
+                    exceptionMap.clear();
+                }
+                resolve();
+            };
+        });
+    }
+    /**
+     * Ensure WebSocket connection exists, creating it if needed.
+     */
+    async _ensureWebSocketConnection() {
+        if (this.websocket && this.websocket.readyState === 1) {
+            return;
+        }
+        await waitForTracing;
+        const span = this.logger.startSpan('sdk.websocket_connection');
+        try {
+            this.sendQueue = new Queue();
+            const websocket_uri = `${this.baseWs}/socket`;
+            this.logger.debug(`Connecting WebSocket`);
+            span.setAttribute('websocket.uri', websocket_uri);
+            span.setAttribute('websocket.state', 'connecting');
+            // Create headers object with trace context for distributed tracing
+            const headers = {};
+            if (this.apiKey) {
+                headers['Authorization'] = `Bearer ${this.apiKey}`;
+            }
+            headers['x-client-session-id'] = this.clientSessionId;
+            // Inject trace context into WebSocket headers for distributed tracing
+            // Execute in span's context to ensure proper trace propagation (like Python's inject(headers, context=ctx))
+            if (span.executeInContext) {
+                span.executeInContext(() => {
+                    injectTraceContext(headers);
+                });
+            }
+            else {
+                // Fallback: pass span context directly
+                injectTraceContext(headers, span);
+            }
+            // Pass null for apiKey since headers already has Authorization
+            const ws = await createWebSocket(websocket_uri, this.apiKey, headers);
+            ws.binaryType = 'arraybuffer';
+            return new Promise((resolve, reject) => {
+                ws.onopen = () => {
+                    this.websocket = ws;
+                    try {
+                        ws._socket?.unref?.();
+                    }
+                    catch {
+                        // Ignore unref errors
+                    }
+                    const readerControl = {
+                        shouldStop: false,
+                        promise: Promise.resolve(),
+                    };
+                    const writerControl = {
+                        shouldStop: false,
+                        promise: Promise.resolve(),
+                    };
+                    readerControl.promise = this.wsBackgroundTaskReader(readerControl).catch((error) => {
+                        this.logger.error('Reader background task crashed', error);
+                    });
+                    writerControl.promise = this.wsBackgroundTaskWriter(writerControl).catch((error) => {
+                        this.logger.error('Writer background task crashed', error);
+                    });
+                    this.tasks = [readerControl, writerControl];
+                    this.logger.info(`WebSocket connected`);
+                    span.setAttribute('websocket.state', 'connected');
+                    span.end();
+                    resolve();
+                };
+                ws.onerror = (error) => {
+                    this.logger.error(`WebSocket connection failed:\n${error.toString()}`);
+                    span.setAttribute('websocket.state', 'error');
+                    span.recordException(error);
+                    span.end();
+                    reject(new WebSocketConnectionError('WebSocket connection failed'));
+                };
+            });
+        }
+        catch (error) {
+            span.setAttribute('websocket.state', 'error');
+            span.recordException(error);
+            span.end();
+            throw error;
+        }
+    }
+    /**
+     * Initialize per-agent data structures.
+     */
+    _initAgentState(uid, parentLogger) {
+        if (!this.uidIidRecvQueue.has(uid)) {
+            this.uidIidRecvQueue.set(uid, new Map());
+        }
+        if (!this.uidIidException.has(uid)) {
+            this.uidIidException.set(uid, new Map());
+        }
+        if (parentLogger) {
+            this.uidToLogger.set(uid, parentLogger);
+        }
+    }
+    /**
+     * Create new agent - matches Python new_agent
+     */
+    async newAgent(cmar, parentLogger) {
+        await waitForTracing;
+        this.refConnection();
+        const logger = parentLogger ?? this.logger;
+        const span = logger.startSpan('sdk.new_agent');
+        try {
+            // Wait if currently stopping
+            while (this.isStopping) {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+            // Restart if stopped
+            if (this.isStopped) {
+                this.isStopped = false;
+            }
+            if (!this.baseHttp || !this.baseWs) {
+                logger.error('Endpoints not set');
+                const error = new ConnectionError('Base HTTP and WS endpoints must be set');
+                enrichError(error, { sessionId: this.clientSessionId });
+                throw error;
+            }
+            cmar.protocol = `typescript/${version}`;
+            const uri = `${this.baseHttp}/agent/create`;
+            logger.debug(`Creating agent (model=${cmar.model})`);
+            span.setAttribute('agent.model', cmar.model || 'unknown');
+            span.setAttribute('agent.streaming', cmar.streaming || false);
+            const requestBody = {
+                ...cmar,
+                warp_globals_payload: uint8ArrayToBase64(cmar.warp_globals_payload),
+            };
+            // Build headers with trace context for distributed tracing
+            const headers = this.buildHeaders({ 'Content-Type': 'application/json' });
+            injectTraceContext(headers, span);
+            const response = await fetch(uri, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(requestBody),
+            });
+            if (response.status === 426) {
+                const errorData = await response.json();
+                const detail = errorData?.detail || 'SDK version is no longer supported.';
+                const error = new SDKUnsupportedError(detail);
+                enrichError(error, { sessionId: this.clientSessionId });
+                throw error;
+            }
+            if (!response.ok) {
+                logger.error(`HTTP request failed: ${response.status} ${response.statusText}`);
+                const error = new ConnectionError(`HTTP ${response.status}: ${response.statusText}`);
+                enrichError(error, { sessionId: this.clientSessionId });
+                throw error;
+            }
+            const warning = response.headers.get('X-SDK-Warning');
+            if (warning === 'deprecated') {
+                const message = response.headers.get('X-SDK-Upgrade-Message');
+                if (message) {
+                    logger.warn(message);
+                }
+            }
+            const uid = await response.text();
+            logger.info('Created agent');
+            span.setAttribute('agent.uid', uid);
+            await this._ensureWebSocketConnection();
+            this.knownUids.add(uid);
+            this._initAgentState(uid, parentLogger);
+            return uid;
+        }
+        catch (error) {
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Create new agent invocation - matches Python invoke_agent
+     */
+    async invokeAgent(params, parentLogger) {
+        await waitForTracing;
+        this.refConnection();
+        const { uid, warpLocalsPayload, taskDesc, streaming } = params;
+        const logger = parentLogger ?? this.logger;
+        const span = logger.startSpan('sdk.invoke_agent');
+        const invLogger = logger.withScope('inv');
+        try {
+            if (this.isStopping) {
+                logger.error('Cannot invoke agent: session manager is stopping');
+                const error = new ConnectionError('Session manager is stopping');
+                enrichError(error, { uid, sessionId: this.clientSessionId });
+                throw error;
+            }
+            if (!this.baseHttp || !this.baseWs) {
+                logger.error('Endpoints not set');
+                const error = new ConnectionError('Base HTTP and WS endpoints must be set');
+                enrichError(error, { uid, sessionId: this.clientSessionId });
+                throw error;
+            }
+            // Add attributes matching Python SDK
+            span.setAttribute('agent.uid', uid);
+            span.setAttribute('agent.task_desc', typeof taskDesc === 'string' ? taskDesc : taskDesc.template);
+            span.setAttribute('invocation.streaming', streaming);
+            const matchId = this.idIssuer();
+            const msg = {
+                type: 'invoke',
+                match_id: matchId,
+                uid: uid,
+                warp_locals_payload: warpLocalsPayload,
+                timestamp: new Date().toISOString(),
+                prompt: taskDesc,
+                streaming: streaming,
+            };
+            invLogger.debug(`Invoking with match_id=${matchId}`);
+            const iidPromise = new Promise((resolve, reject) => {
+                this.matchIid.set(matchId, { resolve, reject });
+            });
+            this.sendQueue.put(msg);
+            const iid = await iidPromise;
+            this.iidToUid.set(iid, uid);
+            invLogger.info(`Invocation created with iid=${iid}`);
+            span.setAttribute('invocation.iid', iid);
+            this.uidIidRecvQueue.get(uid).set(iid, new Queue());
+            const recvQueue = this.uidIidRecvQueue.get(uid).get(iid);
+            const { resolvers, promise: exceptionPromise } = (() => {
+                let resolve;
+                let reject;
+                const promise = new Promise((res, rej) => {
+                    resolve = res;
+                    reject = rej;
+                });
+                return { resolvers: { resolve, reject, promise }, promise };
+            })();
+            this.uidIidException.get(uid).set(iid, resolvers);
+            return {
+                send_message: async (data) => {
+                    const dataMsg = {
+                        type: 'data',
+                        uid,
+                        iid,
+                        data,
+                        timestamp: new Date().toISOString(),
+                    };
+                    this.sendQueue.put(dataMsg);
+                    invLogger.debug(`Queued ${data.length} bytes to send`);
+                },
+                recv_message: async () => {
+                    const data = await recvQueue.get();
+                    invLogger.debug(`Received ${data.length} bytes`);
+                    return data;
+                },
+                exception: exceptionPromise,
+                iid,
+            };
+        }
+        catch (error) {
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+            this.unrefConnection();
+        }
+    }
+    /**
+     * Echo streaming endpoint
+     */
+    async *echo(cancelSignal, uid, iid) {
+        if (!this.baseHttp) {
+            const error = new ConnectionError('Base HTTP endpoint must be set');
+            enrichError(error, { uid, iid, sessionId: this.clientSessionId });
+            throw error;
+        }
+        const endpoint = `/echo/${uid}${iid ? `/${iid}` : ''}`;
+        const url = `${this.baseHttp}${endpoint}`;
+        this.logger.debug(`Starting echo stream for ${uid}${iid ? `/${iid}` : ''}`);
+        let reader = null;
+        let response = null;
+        const abortController = new AbortController();
+        try {
+            response = await fetch(url, {
+                method: 'GET',
+                headers: this.buildHeaders({ Accept: 'text/event-stream' }),
+                signal: AbortSignal.any([abortController.signal, cancelSignal]),
+                bodyTimeout: 0, // Node.js only
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => 'Unknown error');
+                const error = new ServerError(`HTTP ${response.status}: ${response.statusText} - ${errorText}`);
+                enrichError(error, { uid, iid, sessionId: this.clientSessionId });
+                throw error;
+            }
+            if (!response.body) {
+                const error = new ServerError('Response body is null - server may not support streaming');
+                enrichError(error, { uid, iid, sessionId: this.clientSessionId });
+                throw error;
+            }
+            reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            let chunkCount = 0;
+            const maxChunks = 10000; // Prevent infinite loops
+            const maxBufferSize = 1024 * 1024; // 1MB buffer limit
+            let isStreaming = false;
+            try {
+                while (chunkCount < maxChunks) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        this.logger.debug(`Echo stream completed normally after ${chunkCount} chunks`);
+                        break;
+                    }
+                    // Prevent buffer overflow
+                    if (buffer.length > maxBufferSize) {
+                        this.logger.warn('Buffer size exceeded, clearing buffer');
+                        buffer = '';
+                    }
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop() || '';
+                    for (const line of lines) {
+                        if (!line.trim()) {
+                            continue;
+                        }
+                        try {
+                            const logmsg = JSON.parse(line);
+                            const typ = logmsg.type;
+                            if (typ === 'sm_invocation_exit') {
+                                this.logger.debug('Received invocation exit signal, ending stream');
+                                return;
+                            }
+                            if (typ === 'sm_monad' && logmsg.body) {
+                                const body = JSON.parse(logmsg.body);
+                                if (body.system)
+                                    continue;
+                                if (body.type === 'stream_chunk') {
+                                    isStreaming = true;
+                                    const delta = body.args[0];
+                                    if (delta && delta.content) {
+                                        yield { role: 'agent', content: delta.content };
+                                        chunkCount++;
+                                    }
+                                }
+                                else if (body.type === 'delta') {
+                                    const delta = body.args[0];
+                                    if (delta && delta.content) {
+                                        const role = makeRole(delta.role, delta.username);
+                                        if (role === 'system') {
+                                            // Skip system messages
+                                            continue;
+                                        }
+                                        else if (isStreaming && role === 'agent') {
+                                            // Skip agent messages as they're already handled in stream_chunk
+                                            continue;
+                                        }
+                                        yield { role, content: delta.content };
+                                        chunkCount++;
+                                    }
+                                }
+                            }
+                        }
+                        catch (parseError) {
+                            this.logger.warn('Failed to parse echo line', parseError);
+                            // Continue processing other lines instead of failing completely
+                        }
+                    }
+                }
+                if (chunkCount >= maxChunks) {
+                    this.logger.warn(`Echo stream stopped after ${maxChunks} chunks (safety limit)`);
+                }
+            }
+            finally {
+                if (reader) {
+                    try {
+                        reader.releaseLock();
+                    }
+                    catch (releaseError) {
+                        this.logger.warn('Failed to release reader lock', releaseError);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError' && cancelSignal.aborted) {
+                // this is expected after result was received
+                this.logger.debug('Echo stream aborted by caller');
+                return;
+            }
+            this.logger.error('Echo stream error', error);
+            // Provide more specific error information
+            if (error instanceof TypeError && error.message.includes('fetch')) {
+                const enrichedError = new ConnectionError(`Network error during echo stream: ${error.message}`);
+                enrichError(enrichedError, { uid, iid, sessionId: this.clientSessionId });
+                throw enrichedError;
+            }
+            else if (error instanceof Error && error.message.includes('HTTP')) {
+                const enrichedError = new ServerError(`Server error during echo stream: ${error.message}`);
+                enrichError(enrichedError, { uid, iid, sessionId: this.clientSessionId });
+                throw enrichedError;
+            }
+            else {
+                const enrichedError = new ServerError(`Echo stream failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                enrichError(enrichedError, { uid, iid, sessionId: this.clientSessionId });
+                throw enrichedError;
+            }
+        }
+        finally {
+            // Abort the fetch request to close the underlying socket
+            try {
+                abortController.abort();
+            }
+            catch {
+                // Ignore abort errors
+            }
+            // Ensure cleanup even if an error occurs
+            if (reader) {
+                try {
+                    reader.releaseLock();
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+    }
+    /**
+     * Fetch logs for a specific agent and optionally a specific invocation.
+     * Matches Python logs() method.
+     */
+    async logs(uid, iid, params) {
+        if (!this.baseHttp) {
+            throw new ConnectionError('Base HTTP endpoint must be set');
+        }
+        let endpoint = `/logs/${uid}`;
+        if (iid) {
+            endpoint += `/${iid}`;
+        }
+        const url = new URL(`${this.baseHttp}${endpoint}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.append(key, String(value));
+            }
+        }
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new ServerError(`HTTP ${response.status}: ${response.statusText} - ${errorText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Fetch and calculate usage for a specific invocation.
+     * Handles chat-completions API's cumulative token reporting by subtracting previous totals.
+     *
+     * @param uid - Agent UID
+     * @param iid - Invocation ID
+     * @param lastTotal - Previous cumulative total (for cross-invocation adjustment)
+     * @returns Object containing the usage for this invocation and the new cumulative total
+     */
+    async fetchUsage(uid, iid, lastTotal) {
+        // Fetch logs for this invocation and sum usages
+        let total = Usage.zero();
+        const logs = await this.logs(uid, iid, { type: 'sm_inference_usage' });
+        for (const log of logs) {
+            const logUsage = log.usage;
+            if (logUsage) {
+                total = total.add(Usage.fromCompletions(logUsage, total));
+            }
+        }
+        let usage = total;
+        if (lastTotal) {
+            // Subtract previous cumulative total, but keep output_tokens as-is
+            // since output_tokens is already absolute (not cumulative)
+            usage = total.sub(lastTotal.replace({ outputTokens: 0 }));
+        }
+        return { usage, newTotal: total };
+    }
+    /**
+     * Check if agent exists - matches Python agent_exists
+     */
+    agentExists(uid) {
+        return this.knownUids.has(uid) && this.websocket !== null && this.websocket.readyState === 1; // 1 = OPEN
+    }
+    /**
+     * Get uid from iid (used for parent-child agent tracking)
+     */
+    getUidForIid(iid) {
+        return this.iidToUid.get(iid);
+    }
+    /**
+     * Destroy an agent on the server
+     */
+    async destroyAgent(uid) {
+        if (!this.baseHttp) {
+            this.logger.warn('Cannot destroy agent: baseHttp not set');
+            return;
+        }
+        const span = this.logger.startSpan('sdk.destroy_agent');
+        span.setAttribute('agent.uid', uid);
+        try {
+            const uri = `${this.baseHttp}/agent/destroy/${uid}`;
+            this.logger.debug(`Destroying agent ${uid.slice(0, 8)}`);
+            const response = await fetch(uri, {
+                method: 'DELETE',
+                headers: this.buildHeaders(),
+            });
+            if (response.ok) {
+                this.logger.debug(`Destroyed agent ${uid.slice(0, 8)}`);
+            }
+            else {
+                this.logger.info(`Failed to destroy agent: HTTP ${response.status} ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            this.logger.debug(`Failed to destroy agent ${uid.slice(0, 8)} (server may be down): ${error.message}`);
+            span.recordException(error);
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Close a specific agent's resources (does not close the shared WebSocket)
+     */
+    async closeAgent(uid) {
+        const logger = this.uidToLogger.get(uid) ?? this.logger;
+        logger.debug(`Closing agent ${uid.slice(0, 8)}`);
+        // Close receive queues for this uid
+        const recvMap = this.uidIidRecvQueue.get(uid);
+        if (recvMap) {
+            for (const queue of recvMap.values()) {
+                queue.close();
+            }
+        }
+        // Clean up iidToUid entries for this uid
+        for (const [iid, mappedUid] of this.iidToUid.entries()) {
+            if (mappedUid === uid) {
+                this.iidToUid.delete(iid);
+            }
+        }
+        // Clean up per-agent maps
+        this.uidIidRecvQueue.delete(uid);
+        this.uidIidException.delete(uid);
+        this.knownUids.delete(uid);
+        this.uidToLogger.delete(uid);
+        logger.debug(`Closed agent ${uid.slice(0, 8)}`);
+        // Finally, destroy the agent on the server
+        await this.destroyAgent(uid);
+        this.unrefConnection();
+    }
+    /**
+     * Stop all connections and cleanup resources
+     */
+    async stop() {
+        if (this.isStopping || this.isStopped)
+            return;
+        this.isStopping = true;
+        const span = this.logger.startSpan('stop');
+        try {
+            const agentCount = this.knownUids.size;
+            this.logger.debug(`CSM Stop: stopping with ${agentCount} agent(s)`);
+            span.setAttribute('agent_count', agentCount);
+            // Close all agents (cleans up per-agent state and destroys on server)
+            const uids = Array.from(this.knownUids);
+            await Promise.allSettled(uids.map((uid) => this.closeAgent(uid)));
+            // Close send queue
+            if (this.sendQueue) {
+                this.sendQueue.close();
+                this.sendQueue = null;
+            }
+            // Close WebSocket gracefully
+            if (this.websocket) {
+                try {
+                    // 0 = CONNECTING, 1 = OPEN
+                    if (this.websocket.readyState === 0 || this.websocket.readyState === 1) {
+                        this.websocket.close(1000, 'Normal closure');
+                    }
+                }
+                catch (error) {
+                    this.logger.warn('Failed to close WebSocket', error);
+                }
+                this.websocket = null;
+            }
+            // Stop tasks
+            if (this.tasks) {
+                const [readerControl, writerControl] = this.tasks;
+                readerControl.shouldStop = true;
+                writerControl.shouldStop = true;
+                await Promise.allSettled([readerControl.promise, writerControl.promise]);
+                this.tasks = null;
+            }
+            this.logger.debug('All resources cleaned up');
+            this.isStopped = true;
+            // Ensure invocation guard is cleared
+            if (this.invocationGuard) {
+                clearInterval(this.invocationGuard);
+                this.invocationGuard = null;
+            }
+            this.activeConnectionCount = 0;
+            // End session span when closing the entire ClientSessionManager
+            if (this.sessionSpan) {
+                this.sessionSpan.setAttribute('sdk.agents_created', agentCount);
+                this.sessionSpan.end();
+                this.sessionSpan = null;
+                this.logger.debug('Ended session span');
+            }
+        }
+        finally {
+            this.isStopping = false;
+            span.end();
+        }
+    }
+    /**
+     * Close all connections and cleanup resources
+     */
+    async close() {
+        return this.stop();
+    }
+}
+const __globalScope = globalThis;
+export const __AGENTIC_MANAGER = __globalScope.__AGENTICA_AGENTIC_MANAGER ??
+    (__globalScope.__AGENTICA_AGENTIC_MANAGER = new ClientSessionManager({}));
+export const __AGENTIC_PROTO_VER = `typescript/${version}`;