@love-moon/conductor-sdk 0.2.17 → 0.2.19

package/dist/backend/client.d.ts

@@ -74,6 +74,7 @@ export declare class BackendApiClient {
         id?: string;
         projectId: string;
         title: string;
+        status?: string;
         backendType?: string;
         sessionId?: string | null;
         sessionFilePath?: string | null;

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import { ConductorConfig } from './config/index.js';
 import { MessageRouter } from './message/index.js';
 import { DownstreamCursorStore, DurableUpstreamOutboxStore } from './outbox/index.js';
 import { SessionDiskStore, SessionManager } from './session/index.js';
-import { ConductorWebSocketClient } from './ws/index.js';
+import { ConductorWebSocketClient, WebSocketConnectedEvent, WebSocketDisconnectEvent } from './ws/index.js';
 type BackendApiLike = Pick<BackendApiClient, 'listProjects' | 'createProject' | 'listTasks' | 'createTask' | 'updateTask' | 'commitSdkMessage' | 'commitTaskStatusUpdate' | 'commitAgentCommandAck' | 'commitTaskStopAck' | 'matchProjectByPath' | 'getProject' | 'updateProject'>;
 type RealtimeClientLike = Pick<ConductorWebSocketClient, 'registerHandler' | 'connect' | 'disconnect' | 'sendJson'>;
 export interface ConductorClientConnectOptions {
@@ -21,10 +21,8 @@ export interface ConductorClientConnectOptions {
     upstreamOutbox?: DurableUpstreamOutboxStore;
     downstreamCursorStore?: DownstreamCursorStore;
     agentHost?: string;
-    onConnected?: (event: {
-        isReconnect: boolean;
-    }) => void;
-    onDisconnected?: () => void;
+    onConnected?: (event: WebSocketConnectedEvent) => void;
+    onDisconnected?: (event: WebSocketDisconnectEvent) => void;
     onStopTask?: (event: StopTaskEvent) => Promise<void> | void;
 }
 interface ConductorClientInit {

package/dist/client.js

@@ -5,7 +5,7 @@ import { getPlanLimitMessageFromError } from './limits/index.js';
 import { MessageRouter } from './message/index.js';
 import { DownstreamCursorStore, DurableUpstreamOutboxStore, normalizeDownstreamCommandCursor, } from './outbox/index.js';
 import { SessionDiskStore, SessionManager, currentHostname } from './session/index.js';
-import { ConductorWebSocketClient } from './ws/index.js';
+import { ConductorWebSocketClient, } from './ws/index.js';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class ConductorClient {
     config;
@@ -131,6 +131,7 @@ export class ConductorClient {
                 id: taskId,
                 projectId,
                 title,
+                status: 'running',
                 backendType,
                 sessionId: logicalSessionId,
                 sessionFilePath: explicitSessionFilePath,
@@ -841,6 +842,8 @@ function formatMessagesResponse(messages) {
             role: msg.role,
             content: msg.content,
             ack_token: msg.ackToken,
+            metadata: msg.metadata ?? undefined,
+            attachments: msg.attachments?.length ? msg.attachments : undefined,
             created_at: msg.createdAt.toISOString(),
         })),
         next_ack_token: messages.length ? messages[messages.length - 1].ackToken ?? null : null,

package/dist/message/router.d.ts

@@ -16,6 +16,8 @@ export declare class MessageRouter {
     private resolveMessageId;
     private coerceRole;
     private coerceContent;
+    private coerceMetadata;
+    private coerceAttachments;
     private formatActionContent;
     private ensureSession;
 }

package/dist/message/router.js

@@ -26,6 +26,8 @@ export class MessageRouter {
                 role: this.coerceRole(data.role, 'user'),
                 content: this.coerceContent(data.content),
                 ackToken: data.ack_token ? String(data.ack_token) : null,
+                metadata: this.coerceMetadata(data.metadata),
+                attachments: this.coerceAttachments(data.attachments),
             });
             await this.notify(taskId);
         }
@@ -36,6 +38,8 @@ export class MessageRouter {
                 role: this.coerceRole(data.role, 'action'),
                 content: this.formatActionContent(data),
                 ackToken: data.ack_token ? String(data.ack_token) : null,
+                metadata: this.coerceMetadata(data.metadata),
+                attachments: this.coerceAttachments(data.attachments),
             });
             await this.notify(taskId);
         }
@@ -92,6 +96,20 @@ export class MessageRouter {
             return String(content);
         }
     }
+    coerceMetadata(metadata) {
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+            return null;
+        }
+        return { ...metadata };
+    }
+    coerceAttachments(attachments) {
+        if (!Array.isArray(attachments)) {
+            return [];
+        }
+        return attachments
+            .filter((entry) => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+            .map((entry) => ({ ...entry }));
+    }
     formatActionContent(data) {
         if (typeof data.content === 'string' && data.content.trim()) {
             return data.content;

package/dist/session/manager.d.ts

@@ -1,8 +1,11 @@
+type JsonRecord = Record<string, unknown>;
 export interface MessageInput {
     messageId: string;
     role: string;
     content: string;
     ackToken?: string | null;
+    metadata?: JsonRecord | null;
+    attachments?: JsonRecord[];
 }
 export declare class MessageRecord {
     readonly messageId: string;
@@ -10,6 +13,8 @@ export declare class MessageRecord {
     readonly content: string;
     readonly createdAt: Date;
     readonly ackToken?: string | null;
+    readonly metadata?: JsonRecord | null;
+    readonly attachments: JsonRecord[];
     constructor(init: MessageInput);
 }
 export declare class SessionState {
@@ -37,3 +42,4 @@ export declare class SessionManager {
     endSession(taskId: string): Promise<void>;
     private ensureEvent;
 }
+export {};

package/dist/session/manager.js

@@ -1,15 +1,33 @@
 import { EventEmitter } from 'node:events';
+function normalizeJsonRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return { ...value };
+}
+function normalizeJsonRecordArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((entry) => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+        .map((entry) => ({ ...entry }));
+}
 export class MessageRecord {
     messageId;
     role;
     content;
     createdAt;
     ackToken;
+    metadata;
+    attachments;
     constructor(init) {
         this.messageId = init.messageId;
         this.role = init.role;
         this.content = init.content;
         this.ackToken = init.ackToken;
+        this.metadata = normalizeJsonRecord(init.metadata);
+        this.attachments = normalizeJsonRecordArray(init.attachments);
         this.createdAt = new Date();
     }
 }

package/dist/ws/client.d.ts

@@ -1,9 +1,17 @@
 import { ConductorConfig } from '../config/index.js';
 export type WebSocketHandler = (payload: Record<string, any>) => Promise<void> | void;
+export interface WebSocketCloseInfo {
+    code?: number | null;
+    reason?: string | null;
+}
 export interface WebSocketLike {
     send(data: string): Promise<void> | void;
     ping(): Promise<void> | void;
     close(): Promise<void> | void;
+    terminate?(): Promise<void> | void;
+    onPong?(handler: () => void): void;
+    onCloseInfo?(handler: (info: WebSocketCloseInfo) => void): void;
+    onErrorInfo?(handler: (error: unknown) => void): void;
     closed?: boolean;
     [Symbol.asyncIterator](): AsyncIterableIterator<string>;
 }
@@ -11,16 +19,35 @@ export interface ConnectOptions {
     headers: Record<string, string>;
 }
 export type ConnectImpl = (url: string, options: ConnectOptions) => Promise<WebSocketLike>;
+export interface WebSocketConnectedEvent {
+    isReconnect: boolean;
+    connectedAt: number;
+}
+export interface WebSocketPongEvent {
+    at: number;
+    latencyMs: number | null;
+}
+export interface WebSocketDisconnectEvent {
+    reason: string;
+    disconnectedAt: number;
+    connectedAt: number | null;
+    closeCode: number | null;
+    closeReason: string | null;
+    socketError: string | null;
+    missedPongs: number;
+    lastPingAt: number | null;
+    lastPongAt: number | null;
+    lastMessageAt: number | null;
+}
 export interface WebSocketClientOptions {
     reconnectDelay?: number;
     heartbeatInterval?: number;
     extraHeaders?: Record<string, string>;
     connectImpl?: ConnectImpl;
     hostName?: string;
-    onConnected?: (event: {
-        isReconnect: boolean;
-    }) => void;
-    onDisconnected?: () => void;
+    onConnected?: (event: WebSocketConnectedEvent) => void;
+    onDisconnected?: (event: WebSocketDisconnectEvent) => void;
+    onPong?: (event: WebSocketPongEvent) => void;
     onReconnected?: () => void;
 }
 export declare class ConductorWebSocketClient {
@@ -31,10 +58,12 @@ export declare class ConductorWebSocketClient {
     private readonly connectImpl;
     private readonly onConnected?;
     private readonly onDisconnected?;
+    private readonly onPong?;
     private readonly onReconnected?;
     private readonly handlers;
     private readonly extraHeaders;
     private conn;
+    private runtime;
     private stop;
     private listenTask;
     private heartbeatTask;
@@ -45,6 +74,7 @@ export declare class ConductorWebSocketClient {
     registerHandler(handler: WebSocketHandler): void;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    forceReconnect(reason?: string): Promise<void>;
     sendJson(payload: Record<string, any>): Promise<void>;
     private ensureConnection;
     private openConnection;
@@ -59,4 +89,11 @@ export declare class ConductorWebSocketClient {
     private isConnectionClosed;
     private sendWithReconnect;
     private isNotOpenError;
+    private createRuntime;
+    private attachConnectionObservers;
+    private getRuntime;
+    private markDisconnectReason;
+    private buildDisconnectEvent;
+    private closeConnection;
+    private terminateConnection;
 }

package/dist/ws/client.js

@@ -16,10 +16,12 @@ export class ConductorWebSocketClient {
     connectImpl;
     onConnected;
     onDisconnected;
+    onPong;
     onReconnected;
     handlers = [];
     extraHeaders;
     conn = null;
+    runtime = null;
     stop = false;
     listenTask = null;
     heartbeatTask = null;
@@ -38,6 +40,7 @@ export class ConductorWebSocketClient {
         this.connectImpl = options.connectImpl ?? defaultConnectImpl;
         this.onConnected = options.onConnected;
         this.onDisconnected = options.onDisconnected;
+        this.onPong = options.onPong;
         this.onReconnected = options.onReconnected;
     }
     registerHandler(handler) {
@@ -60,9 +63,20 @@ export class ConductorWebSocketClient {
             this.heartbeatTask = null;
         }
         if (this.conn && !this.isConnectionClosed(this.conn)) {
-            await this.conn.close();
+            this.markDisconnectReason(this.conn, 'manual_disconnect');
+            await this.closeConnection(this.conn);
         }
         this.conn = null;
+        this.runtime = null;
+    }
+    async forceReconnect(reason = 'manual_reconnect') {
+        const conn = this.conn;
+        if (!conn || this.isConnectionClosed(conn)) {
+            await this.openConnection(true);
+            return;
+        }
+        this.markDisconnectReason(conn, reason);
+        await this.terminateConnection(conn);
     }
     async sendJson(payload) {
         await this.ensureConnection();
@@ -83,15 +97,19 @@ export class ConductorWebSocketClient {
             while (!this.stop) {
                 try {
                     const headers = { Authorization: `Bearer ${this.token}`, ...this.extraHeaders };
-                    this.conn = await this.connectImpl(this.url, { headers });
+                    const conn = await this.connectImpl(this.url, { headers });
+                    const runtime = this.createRuntime(conn);
+                    this.attachConnectionObservers(runtime);
+                    this.conn = conn;
+                    this.runtime = runtime;
                     const isReconnect = this.hasConnectedAtLeastOnce;
                     this.hasConnectedAtLeastOnce = true;
-                    this.notifyConnected(isReconnect);
+                    this.notifyConnected({ isReconnect, connectedAt: runtime.connectedAt });
                     if (isReconnect) {
                         this.notifyReconnected();
                     }
-                    this.listenTask = this.listenLoop(this.conn);
-                    this.heartbeatTask = this.heartbeatLoop(this.conn);
+                    this.listenTask = this.listenLoop(conn);
+                    this.heartbeatTask = this.heartbeatLoop(conn);
                     return;
                 }
                 catch (error) {
@@ -124,10 +142,26 @@ export class ConductorWebSocketClient {
         try {
             while (!this.stop && !this.isConnectionClosed(conn)) {
                 await wait(this.heartbeatInterval, this.waitController.signal);
+                if (this.stop || conn !== this.conn) {
+                    return;
+                }
+                const runtime = this.getRuntime(conn);
+                if (!runtime) {
+                    return;
+                }
+                if (runtime.supportsPongTracking && runtime.waitingForPong) {
+                    runtime.missedPongs += 1;
+                    runtime.disconnectReason = 'pong_timeout';
+                    await this.terminateConnection(conn);
+                    break;
+                }
+                runtime.lastPingAt = Date.now();
+                runtime.waitingForPong = runtime.supportsPongTracking;
                 try {
                     await conn.ping();
                 }
                 catch {
+                    this.markDisconnectReason(conn, 'ping_failed');
                     break;
                 }
             }
@@ -140,11 +174,17 @@ export class ConductorWebSocketClient {
         if (this.stop || conn !== this.conn) {
             return;
         }
+        const runtime = this.getRuntime(conn);
         this.conn = null;
-        this.notifyDisconnected();
+        this.runtime = null;
+        this.notifyDisconnected(this.buildDisconnectEvent(runtime));
         await this.openConnection(true);
     }
     async dispatch(message) {
+        const now = Date.now();
+        if (this.runtime) {
+            this.runtime.lastMessageAt = now;
+        }
         let payload;
         try {
             payload = JSON.parse(message);
@@ -159,12 +199,12 @@ export class ConductorWebSocketClient {
             }
         }
     }
-    notifyConnected(isReconnect) {
+    notifyConnected(event) {
         if (!this.onConnected) {
             return;
         }
         try {
-            this.onConnected({ isReconnect });
+            this.onConnected(event);
         }
         catch {
             // Swallow callback errors to avoid impacting reconnect behavior.
@@ -181,12 +221,12 @@ export class ConductorWebSocketClient {
             // Swallow callback errors to avoid impacting reconnect behavior.
         }
     }
-    notifyDisconnected() {
+    notifyDisconnected(event) {
         if (!this.onDisconnected) {
             return;
         }
         try {
-            this.onDisconnected();
+            this.onDisconnected(event);
         }
         catch {
             // Swallow callback errors to avoid impacting reconnect behavior.
@@ -222,8 +262,10 @@ export class ConductorWebSocketClient {
                 }
                 attemptedReconnect = true;
                 if (this.conn === conn) {
+                    this.markDisconnectReason(conn, 'send_reconnect');
                     this.conn = null;
-                    this.notifyDisconnected();
+                    this.notifyDisconnected(this.buildDisconnectEvent(this.getRuntime(conn)));
+                    this.runtime = null;
                 }
                 await this.openConnection(true);
             }
@@ -235,6 +277,100 @@ export class ConductorWebSocketClient {
         const message = error instanceof Error ? error.message : String(error);
         return message.toLowerCase().includes('websocket is not open');
     }
+    createRuntime(conn) {
+        const connectedAt = Date.now();
+        return {
+            conn,
+            connectedAt,
+            supportsPongTracking: typeof conn.onPong === 'function',
+            lastMessageAt: null,
+            lastPingAt: null,
+            lastPongAt: connectedAt,
+            waitingForPong: false,
+            missedPongs: 0,
+            disconnectReason: null,
+            closeCode: null,
+            closeReason: null,
+            socketError: null,
+        };
+    }
+    attachConnectionObservers(runtime) {
+        runtime.conn.onPong?.(() => {
+            const activeRuntime = this.getRuntime(runtime.conn);
+            if (!activeRuntime) {
+                return;
+            }
+            const at = Date.now();
+            const latencyMs = activeRuntime.lastPingAt ? at - activeRuntime.lastPingAt : null;
+            activeRuntime.lastPongAt = at;
+            activeRuntime.waitingForPong = false;
+            activeRuntime.missedPongs = 0;
+            if (this.onPong) {
+                try {
+                    this.onPong({ at, latencyMs });
+                }
+                catch {
+                    // Swallow callback errors to avoid impacting reconnect behavior.
+                }
+            }
+        });
+        runtime.conn.onCloseInfo?.((info) => {
+            const activeRuntime = this.getRuntime(runtime.conn);
+            if (!activeRuntime) {
+                return;
+            }
+            activeRuntime.closeCode = typeof info.code === 'number' ? info.code : null;
+            activeRuntime.closeReason = normalizeOptionalString(info.reason);
+        });
+        runtime.conn.onErrorInfo?.((error) => {
+            const activeRuntime = this.getRuntime(runtime.conn);
+            if (!activeRuntime) {
+                return;
+            }
+            activeRuntime.socketError = error instanceof Error ? error.message : String(error);
+            if (!activeRuntime.disconnectReason) {
+                activeRuntime.disconnectReason = 'socket_error';
+            }
+        });
+    }
+    getRuntime(conn) {
+        if (!this.runtime || this.runtime.conn !== conn) {
+            return null;
+        }
+        return this.runtime;
+    }
+    markDisconnectReason(conn, reason) {
+        const runtime = this.getRuntime(conn);
+        if (runtime && !runtime.disconnectReason) {
+            runtime.disconnectReason = reason;
+        }
+    }
+    buildDisconnectEvent(runtime) {
+        return {
+            reason: runtime?.disconnectReason || 'connection_lost',
+            disconnectedAt: Date.now(),
+            connectedAt: runtime?.connectedAt ?? null,
+            closeCode: runtime?.closeCode ?? null,
+            closeReason: runtime?.closeReason ?? null,
+            socketError: runtime?.socketError ?? null,
+            missedPongs: runtime?.missedPongs ?? 0,
+            lastPingAt: runtime?.lastPingAt ?? null,
+            lastPongAt: runtime?.lastPongAt ?? null,
+            lastMessageAt: runtime?.lastMessageAt ?? null,
+        };
+    }
+    async closeConnection(conn) {
+        if (typeof conn.close === 'function') {
+            await conn.close();
+        }
+    }
+    async terminateConnection(conn) {
+        if (typeof conn.terminate === 'function') {
+            await conn.terminate();
+            return;
+        }
+        await this.closeConnection(conn);
+    }
 }
 async function wait(ms, signal) {
     if (!signal) {
@@ -276,16 +412,34 @@ class WsAdapter {
     ws;
     queue = [];
     waiters = [];
+    pongHandlers = new Set();
+    closeInfoHandlers = new Set();
+    errorHandlers = new Set();
     closed = false;
     constructor(ws) {
         this.ws = ws;
         ws.on('message', (data) => this.enqueue(data.toString()));
-        ws.on('close', () => {
+        ws.on('pong', () => {
+            for (const handler of this.pongHandlers) {
+                handler();
+            }
+        });
+        ws.on('close', (code, reason) => {
             this.closed = true;
+            const closeInfo = {
+                code,
+                reason: normalizeOptionalString(reason?.toString()),
+            };
+            for (const handler of this.closeInfoHandlers) {
+                handler(closeInfo);
+            }
             this.enqueue(null);
         });
-        ws.on('error', () => {
+        ws.on('error', (error) => {
             this.closed = true;
+            for (const handler of this.errorHandlers) {
+                handler(error);
+            }
             this.enqueue(null);
         });
     }
@@ -323,6 +477,21 @@ class WsAdapter {
             this.ws.close();
         });
     }
+    terminate() {
+        if (this.closed) {
+            return;
+        }
+        this.ws.terminate();
+    }
+    onPong(handler) {
+        this.pongHandlers.add(handler);
+    }
+    onCloseInfo(handler) {
+        this.closeInfoHandlers.add(handler);
+    }
+    onErrorInfo(handler) {
+        this.errorHandlers.add(handler);
+    }
     async *[Symbol.asyncIterator]() {
         while (true) {
             const value = await this.nextValue();
@@ -351,3 +520,10 @@ class WsAdapter {
         }
     }
 }
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@love-moon/conductor-sdk",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,5 +27,5 @@
     "typescript": "^5.6.3",
     "vitest": "^2.1.4"
   },
-  "gitCommitId": "c2654e1"
+  "gitCommitId": "346e048"
 }