@love-moon/conductor-sdk 0.2.16 → 0.2.18

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './message/index.js';
 export * from './client.js';
 export * from './context/index.js';
 export * from './limits/index.js';
+export * from './outbox/index.js';

package/dist/index.js

@@ -6,3 +6,4 @@ export * from './message/index.js';
 export * from './client.js';
 export * from './context/index.js';
 export * from './limits/index.js';
+export * from './outbox/index.js';

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/outbox/downstream-cursor-store.d.ts

@@ -0,0 +1,16 @@
+export interface DownstreamCommandCursor {
+    createdAt: string;
+    requestId: string;
+}
+export declare function normalizeDownstreamCommandCursor(value: unknown): DownstreamCommandCursor | null;
+export declare class DownstreamCursorStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    static filePathForProjectPath(projectPath: string, scopeId: string): string;
+    static forProjectPath(projectPath: string, scopeId: string): DownstreamCursorStore;
+    get(agentHost: string): DownstreamCommandCursor | null;
+    hasApplied(agentHost: string, cursor: DownstreamCommandCursor): boolean;
+    advance(agentHost: string, cursor: DownstreamCommandCursor): DownstreamCommandCursor;
+    private loadState;
+    private saveState;
+}

package/dist/outbox/downstream-cursor-store.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const STATE_DIR = path.join('.conductor', 'state');
+const CURSOR_BASENAME = 'agent-downstream-cursor';
+function normalizeCursorValue(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim();
+    return normalized || null;
+}
+function compareCursor(left, right) {
+    const leftTime = Date.parse(left.createdAt);
+    const rightTime = Date.parse(right.createdAt);
+    const normalizedLeftTime = Number.isFinite(leftTime) ? leftTime : 0;
+    const normalizedRightTime = Number.isFinite(rightTime) ? rightTime : 0;
+    if (normalizedLeftTime !== normalizedRightTime) {
+        return normalizedLeftTime < normalizedRightTime ? -1 : 1;
+    }
+    return left.requestId.localeCompare(right.requestId);
+}
+const sanitizeScopeId = (scopeId) => scopeId
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    || 'default';
+export function normalizeDownstreamCommandCursor(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const source = value;
+    const createdAt = normalizeCursorValue(source.created_at) ?? normalizeCursorValue(source.createdAt);
+    const requestId = normalizeCursorValue(source.request_id) ?? normalizeCursorValue(source.requestId);
+    if (!createdAt || !requestId) {
+        return null;
+    }
+    return {
+        createdAt,
+        requestId,
+    };
+}
+export class DownstreamCursorStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = path.resolve(filePath);
+    }
+    static filePathForProjectPath(projectPath, scopeId) {
+        return path.join(projectPath, STATE_DIR, `${CURSOR_BASENAME}.${sanitizeScopeId(scopeId)}.json`);
+    }
+    static forProjectPath(projectPath, scopeId) {
+        return new DownstreamCursorStore(DownstreamCursorStore.filePathForProjectPath(projectPath, scopeId));
+    }
+    get(agentHost) {
+        const state = this.loadState();
+        return state.agents[agentHost] ?? null;
+    }
+    hasApplied(agentHost, cursor) {
+        const current = this.get(agentHost);
+        if (!current) {
+            return false;
+        }
+        return compareCursor(current, cursor) >= 0;
+    }
+    advance(agentHost, cursor) {
+        const state = this.loadState();
+        const current = state.agents[agentHost] ?? null;
+        if (current && compareCursor(current, cursor) >= 0) {
+            return current;
+        }
+        state.agents[agentHost] = cursor;
+        this.saveState(state);
+        return cursor;
+    }
+    loadState() {
+        if (!fs.existsSync(this.filePath)) {
+            return { agents: {} };
+        }
+        try {
+            const contents = fs.readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(contents);
+            if (!parsed || typeof parsed !== 'object' || !parsed.agents || typeof parsed.agents !== 'object') {
+                return { agents: {} };
+            }
+            return { agents: parsed.agents };
+        }
+        catch {
+            return { agents: {} };
+        }
+    }
+    saveState(state) {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tempPath, JSON.stringify(state, null, 2), 'utf-8');
+        fs.renameSync(tempPath, this.filePath);
+    }
+}

package/dist/outbox/index.d.ts

@@ -0,0 +1,2 @@
+export * from './store.js';
+export * from './downstream-cursor-store.js';

package/dist/outbox/index.js

@@ -0,0 +1,2 @@
+export * from './store.js';
+export * from './downstream-cursor-store.js';

package/dist/outbox/store.d.ts

@@ -0,0 +1,31 @@
+export type DurableUpstreamEventType = 'sdk_message' | 'task_status_update' | 'agent_command_ack' | 'task_stop_ack';
+export interface DurableUpstreamEvent {
+    stableId: string;
+    eventType: DurableUpstreamEventType;
+    payload: Record<string, unknown>;
+    createdAt: string;
+    attemptCount: number;
+    lastAttemptAt?: string | null;
+    nextAttemptAt?: string | null;
+}
+export declare class DurableUpstreamOutboxStore {
+    private readonly filePath;
+    private readonly lockPath;
+    constructor(filePath: string);
+    static filePathForProjectPath(projectPath: string, scopeId: string): string;
+    static forProjectPath(projectPath: string, scopeId: string): DurableUpstreamOutboxStore;
+    load(): DurableUpstreamEvent[];
+    upsert(entry: {
+        stableId: string;
+        eventType: DurableUpstreamEventType;
+        payload: Record<string, unknown>;
+    }): DurableUpstreamEvent;
+    remove(stableId: string): void;
+    markRetry(stableId: string, delayMs: number): DurableUpstreamEvent | null;
+    listReady(nowMs?: number): DurableUpstreamEvent[];
+    nextRetryDelay(nowMs?: number): number | null;
+    private loadUnlocked;
+    private saveUnlocked;
+    private withLock;
+    private acquireLock;
+}

package/dist/outbox/store.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const OUTBOX_DIR = path.join('.conductor', 'state');
+const OUTBOX_BASENAME = 'agent-upstream-outbox';
+const LOCK_TIMEOUT_MS = 10_000;
+const LOCK_RETRY_MS = 50;
+const sleepSync = (ms) => {
+    if (ms <= 0)
+        return;
+    try {
+        const buffer = new SharedArrayBuffer(4);
+        const arr = new Int32Array(buffer);
+        Atomics.wait(arr, 0, 0, ms);
+    }
+    catch {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < ms) {
+            // busy wait fallback
+        }
+    }
+};
+const sanitizeScopeId = (scopeId) => scopeId
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    || 'default';
+export class DurableUpstreamOutboxStore {
+    filePath;
+    lockPath;
+    constructor(filePath) {
+        this.filePath = path.resolve(filePath);
+        this.lockPath = `${this.filePath}.lock`;
+    }
+    static filePathForProjectPath(projectPath, scopeId) {
+        return path.join(projectPath, OUTBOX_DIR, `${OUTBOX_BASENAME}.${sanitizeScopeId(scopeId)}.json`);
+    }
+    static forProjectPath(projectPath, scopeId) {
+        return new DurableUpstreamOutboxStore(DurableUpstreamOutboxStore.filePathForProjectPath(projectPath, scopeId));
+    }
+    load() {
+        return this.withLock(() => this.loadUnlocked());
+    }
+    upsert(entry) {
+        return this.withLock(() => {
+            const entries = this.loadUnlocked();
+            const existing = entries.find((candidate) => candidate.stableId === entry.stableId);
+            const record = {
+                stableId: entry.stableId,
+                eventType: entry.eventType,
+                payload: entry.payload,
+                createdAt: existing?.createdAt ?? new Date().toISOString(),
+                attemptCount: existing?.attemptCount ?? 0,
+                lastAttemptAt: existing?.lastAttemptAt ?? null,
+                nextAttemptAt: existing?.nextAttemptAt ?? new Date().toISOString(),
+            };
+            const nextEntries = existing
+                ? entries.map((candidate) => (candidate.stableId === entry.stableId ? record : candidate))
+                : [...entries, record];
+            this.saveUnlocked(nextEntries);
+            return record;
+        });
+    }
+    remove(stableId) {
+        this.withLock(() => {
+            const entries = this.loadUnlocked().filter((candidate) => candidate.stableId !== stableId);
+            this.saveUnlocked(entries);
+        });
+    }
+    markRetry(stableId, delayMs) {
+        return this.withLock(() => {
+            const entries = this.loadUnlocked();
+            const index = entries.findIndex((candidate) => candidate.stableId === stableId);
+            if (index < 0) {
+                return null;
+            }
+            const now = Date.now();
+            const updated = {
+                ...entries[index],
+                attemptCount: entries[index].attemptCount + 1,
+                lastAttemptAt: new Date(now).toISOString(),
+                nextAttemptAt: new Date(now + Math.max(delayMs, 0)).toISOString(),
+            };
+            entries[index] = updated;
+            this.saveUnlocked(entries);
+            return updated;
+        });
+    }
+    listReady(nowMs = Date.now()) {
+        return this.load()
+            .filter((entry) => {
+            if (!entry.nextAttemptAt)
+                return true;
+            const nextAttemptMs = Date.parse(entry.nextAttemptAt);
+            return !Number.isFinite(nextAttemptMs) || nextAttemptMs <= nowMs;
+        });
+    }
+    nextRetryDelay(nowMs = Date.now()) {
+        const entries = this.load();
+        let minDelay = null;
+        for (const entry of entries) {
+            if (!entry.nextAttemptAt) {
+                return 0;
+            }
+            const nextAttemptMs = Date.parse(entry.nextAttemptAt);
+            if (!Number.isFinite(nextAttemptMs)) {
+                return 0;
+            }
+            const delay = Math.max(nextAttemptMs - nowMs, 0);
+            minDelay = minDelay === null ? delay : Math.min(minDelay, delay);
+        }
+        return minDelay;
+    }
+    loadUnlocked() {
+        if (!fs.existsSync(this.filePath)) {
+            return [];
+        }
+        try {
+            const contents = fs.readFileSync(this.filePath, 'utf-8');
+            const parsed = JSON.parse(contents);
+            return Array.isArray(parsed.entries) ? parsed.entries : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    saveUnlocked(entries) {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        const payload = { entries };
+        const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+        fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), 'utf-8');
+        fs.renameSync(tempPath, this.filePath);
+    }
+    withLock(fn) {
+        const release = this.acquireLock();
+        try {
+            return fn();
+        }
+        finally {
+            release();
+        }
+    }
+    acquireLock() {
+        const startedAt = Date.now();
+        fs.mkdirSync(path.dirname(this.lockPath), { recursive: true });
+        while (true) {
+            try {
+                const fd = fs.openSync(this.lockPath, 'wx');
+                return () => {
+                    try {
+                        fs.closeSync(fd);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        fs.unlinkSync(this.lockPath);
+                    }
+                    catch {
+                        // ignore
+                    }
+                };
+            }
+            catch (error) {
+                if (error?.code !== 'EEXIST') {
+                    throw error;
+                }
+                if (Date.now() - startedAt > LOCK_TIMEOUT_MS) {
+                    throw new Error(`Timed out waiting for outbox lock: ${this.lockPath}`);
+                }
+                sleepSync(LOCK_RETRY_MS);
+            }
+        }
+    }
+}

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;
 }