@love-moon/conductor-sdk 0.2.15 → 0.2.17

package/dist/backend/client.d.ts

@@ -4,6 +4,30 @@ export interface BackendClientOptions {
     fetchImpl?: FetchFn;
     timeoutMs?: number;
 }
+export type AgentCommitEvent = {
+    eventType: 'sdk_message';
+    taskId: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    messageId?: string | null;
+} | {
+    eventType: 'task_status_update';
+    taskId: string;
+    status: string;
+    summary?: string | null;
+    statusEventId?: string | null;
+} | {
+    eventType: 'agent_command_ack';
+    requestId: string;
+    taskId?: string | null;
+    accepted?: boolean;
+    commandEventType?: string | null;
+} | {
+    eventType: 'task_stop_ack';
+    taskId: string;
+    requestId: string;
+    accepted?: boolean;
+};
 export declare class BackendApiError extends Error {
     readonly statusCode?: number | undefined;
     readonly details?: unknown | undefined;
@@ -73,6 +97,39 @@ export declare class BackendApiClient {
         content: string;
         metadata?: Record<string, unknown>;
     }): Promise<any>;
+    commitAgentEvents(params: {
+        agentHost: string;
+        events: AgentCommitEvent[];
+    }): Promise<{
+        results: Array<Record<string, unknown>>;
+    }>;
+    commitSdkMessage(params: {
+        agentHost: string;
+        taskId: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+        messageId?: string | null;
+    }): Promise<Record<string, unknown>>;
+    commitTaskStatusUpdate(params: {
+        agentHost: string;
+        taskId: string;
+        status: string;
+        summary?: string | null;
+        statusEventId?: string | null;
+    }): Promise<Record<string, unknown>>;
+    commitAgentCommandAck(params: {
+        agentHost: string;
+        requestId: string;
+        taskId?: string | null;
+        accepted?: boolean;
+        commandEventType?: string | null;
+    }): Promise<Record<string, unknown>>;
+    commitTaskStopAck(params: {
+        agentHost: string;
+        taskId: string;
+        requestId: string;
+        accepted?: boolean;
+    }): Promise<Record<string, unknown>>;
     matchProjectByPath(params: {
         hostname: string;
         path: string;

package/dist/backend/client.js

@@ -152,6 +152,108 @@ export class BackendApiClient {
         });
         return this.parseJson(response);
     }
+    async commitAgentEvents(params) {
+        const response = await this.request('POST', '/agent/events', {
+            body: JSON.stringify({
+                agent_host: params.agentHost,
+                events: params.events.map((event) => {
+                    if (event.eventType === 'sdk_message') {
+                        return {
+                            event_type: event.eventType,
+                            task_id: event.taskId,
+                            content: event.content,
+                            metadata: event.metadata,
+                            message_id: event.messageId ?? undefined,
+                        };
+                    }
+                    if (event.eventType === 'task_status_update') {
+                        return {
+                            event_type: event.eventType,
+                            task_id: event.taskId,
+                            status: event.status,
+                            summary: event.summary ?? undefined,
+                            status_event_id: event.statusEventId ?? undefined,
+                        };
+                    }
+                    if (event.eventType === 'task_stop_ack') {
+                        return {
+                            event_type: event.eventType,
+                            task_id: event.taskId,
+                            request_id: event.requestId,
+                            accepted: event.accepted !== false,
+                        };
+                    }
+                    return {
+                        event_type: event.eventType,
+                        request_id: event.requestId,
+                        task_id: event.taskId ?? undefined,
+                        accepted: event.accepted !== false,
+                        command_event_type: event.commandEventType ?? undefined,
+                    };
+                }),
+            }),
+        });
+        return this.parseJson(response);
+    }
+    async commitSdkMessage(params) {
+        const payload = await this.commitAgentEvents({
+            agentHost: params.agentHost,
+            events: [
+                {
+                    eventType: 'sdk_message',
+                    taskId: params.taskId,
+                    content: params.content,
+                    metadata: params.metadata,
+                    messageId: params.messageId,
+                },
+            ],
+        });
+        return (Array.isArray(payload.results) ? payload.results[0] : null) ?? {};
+    }
+    async commitTaskStatusUpdate(params) {
+        const payload = await this.commitAgentEvents({
+            agentHost: params.agentHost,
+            events: [
+                {
+                    eventType: 'task_status_update',
+                    taskId: params.taskId,
+                    status: params.status,
+                    summary: params.summary,
+                    statusEventId: params.statusEventId,
+                },
+            ],
+        });
+        return (Array.isArray(payload.results) ? payload.results[0] : null) ?? {};
+    }
+    async commitAgentCommandAck(params) {
+        const payload = await this.commitAgentEvents({
+            agentHost: params.agentHost,
+            events: [
+                {
+                    eventType: 'agent_command_ack',
+                    requestId: params.requestId,
+                    taskId: params.taskId,
+                    accepted: params.accepted,
+                    commandEventType: params.commandEventType,
+                },
+            ],
+        });
+        return (Array.isArray(payload.results) ? payload.results[0] : null) ?? {};
+    }
+    async commitTaskStopAck(params) {
+        const payload = await this.commitAgentEvents({
+            agentHost: params.agentHost,
+            events: [
+                {
+                    eventType: 'task_stop_ack',
+                    taskId: params.taskId,
+                    requestId: params.requestId,
+                    accepted: params.accepted,
+                },
+            ],
+        });
+        return (Array.isArray(payload.results) ? payload.results[0] : null) ?? {};
+    }
     async matchProjectByPath(params) {
         const response = await this.request('POST', '/projects/match-path', {
             body: JSON.stringify(params),

package/dist/client.d.ts

@@ -1,9 +1,10 @@
 import { BackendApiClient } from './backend/index.js';
 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';
-type BackendApiLike = Pick<BackendApiClient, 'listProjects' | 'createProject' | 'listTasks' | 'createTask' | 'updateTask' | 'matchProjectByPath' | 'getProject' | 'updateProject'>;
+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 {
     config?: ConductorConfig;
@@ -11,11 +12,14 @@ export interface ConductorClientConnectOptions {
     env?: Record<string, string | undefined>;
     extraEnv?: Record<string, string | undefined>;
     projectPath?: string;
+    deliveryScopeId?: string;
     backendApi?: BackendApiLike;
     wsClient?: RealtimeClientLike;
     sessionManager?: SessionManager;
     sessionStore?: SessionDiskStore;
     messageRouter?: MessageRouter;
+    upstreamOutbox?: DurableUpstreamOutboxStore;
+    downstreamCursorStore?: DownstreamCursorStore;
     agentHost?: string;
     onConnected?: (event: {
         isReconnect: boolean;
@@ -27,11 +31,14 @@ interface ConductorClientInit {
     config: ConductorConfig;
     env: Record<string, string | undefined>;
     projectPath: string;
+    deliveryScopeId: string;
     backendApi: BackendApiLike;
     wsClient: RealtimeClientLike;
     sessionManager: SessionManager;
     sessionStore: SessionDiskStore;
     messageRouter: MessageRouter;
+    upstreamOutbox: DurableUpstreamOutboxStore;
+    downstreamCursorStore: DownstreamCursorStore;
     agentHost: string;
     onStopTask?: (event: StopTaskEvent) => Promise<void> | void;
 }
@@ -49,9 +56,15 @@ export declare class ConductorClient {
     private readonly sessions;
     private readonly sessionStore;
     private readonly messageRouter;
+    private upstreamOutbox;
+    private downstreamCursorStore;
     private readonly agentHost;
     private readonly onStopTask?;
+    private deliveryScopeId;
     private closed;
+    private durableOutboxFlushPromise;
+    private durableOutboxTimer;
+    private durableOutboxTimerDueAt;
     constructor(init: ConductorClientInit);
     static connect(options?: ConductorClientConnectOptions): Promise<ConductorClient>;
     close(): Promise<void>;
@@ -63,6 +76,10 @@ export declare class ConductorClient {
         active_tasks?: string[];
         source?: string;
         metadata?: Record<string, any>;
+        last_applied_cursor?: {
+            created_at: string;
+            request_id: string;
+        };
     }): Promise<Record<string, any>>;
     sendAgentCommandAck(payload: {
         request_id: string;
@@ -86,9 +103,22 @@ export declare class ConductorClient {
     matchProjectByPath(payload?: Record<string, any>): Promise<Record<string, any>>;
     bindProjectPath(projectId: string, payload?: Record<string, any>): Promise<Record<string, any>>;
     private readonly handleBackendEvent;
+    private extractDownstreamCommandContext;
+    private handleStopTaskCommand;
+    private invokeStopTaskHandler;
+    private persistAndCommitUpstreamEvent;
+    private requestDurableOutboxFlush;
+    private hasEarlierPendingSdkMessage;
+    private commitDurableUpstreamEvent;
+    private isRetryableUpstreamError;
+    private computeDurableOutboxRetryDelay;
+    private scheduleDurableOutboxFlush;
+    private clearDurableOutboxTimer;
     private sendEnvelope;
     private maybeAckInboundCommand;
-    private handleStopTaskEvent;
+    private promoteTaskDeliveryScope;
+    private setDeliveryScopeId;
+    private shouldAutoFlushDurableOutbox;
     private resolveHostname;
     private waitForTaskCreation;
     private readIntEnv;

package/dist/client.js

@@ -1,8 +1,9 @@
 import crypto from 'node:crypto';
-import { BackendApiClient } from './backend/index.js';
+import { BackendApiClient, BackendApiError } from './backend/index.js';
 import { loadConfig } from './config/index.js';
 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';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -15,9 +16,15 @@ export class ConductorClient {
     sessions;
     sessionStore;
     messageRouter;
+    upstreamOutbox;
+    downstreamCursorStore;
     agentHost;
     onStopTask;
+    deliveryScopeId;
     closed = false;
+    durableOutboxFlushPromise = null;
+    durableOutboxTimer = null;
+    durableOutboxTimerDueAt = null;
     constructor(init) {
         this.config = init.config;
         this.env = init.env;
@@ -27,8 +34,11 @@ export class ConductorClient {
         this.sessions = init.sessionManager;
         this.sessionStore = init.sessionStore;
         this.messageRouter = init.messageRouter;
+        this.upstreamOutbox = init.upstreamOutbox;
+        this.downstreamCursorStore = init.downstreamCursorStore;
         this.agentHost = init.agentHost;
         this.onStopTask = init.onStopTask;
+        this.deliveryScopeId = init.deliveryScopeId;
         this.wsClient.registerHandler(this.handleBackendEvent);
     }
     static async connect(options = {}) {
@@ -40,25 +50,39 @@ export class ConductorClient {
         const sessionStore = options.sessionStore ?? SessionDiskStore.forBackendUrl(config.backendUrl);
         const messageRouter = options.messageRouter ?? new MessageRouter(sessions);
         const agentHost = resolveAgentHost(env, options.agentHost);
+        const deliveryScopeId = normalizeDeliveryScopeId(options.deliveryScopeId ?? `agent:${agentHost}`);
+        const upstreamOutbox = options.upstreamOutbox ?? DurableUpstreamOutboxStore.forProjectPath(projectPath, deliveryScopeId);
+        const downstreamCursorStore = options.downstreamCursorStore ?? DownstreamCursorStore.forProjectPath(projectPath, deliveryScopeId);
         const wsClient = options.wsClient ??
             new ConductorWebSocketClient(config, {
                 hostName: agentHost,
                 onConnected: options.onConnected,
                 onDisconnected: options.onDisconnected,
+                onReconnected: () => {
+                    if (client.shouldAutoFlushDurableOutbox()) {
+                        void client.requestDurableOutboxFlush(true);
+                    }
+                },
             });
         const client = new ConductorClient({
             config,
             env,
             projectPath,
+            deliveryScopeId,
             backendApi,
             wsClient,
             sessionManager: sessions,
             sessionStore,
             messageRouter,
+            upstreamOutbox,
+            downstreamCursorStore,
             agentHost,
             onStopTask: options.onStopTask,
         });
         await client.wsClient.connect();
+        if (client.shouldAutoFlushDurableOutbox()) {
+            void client.requestDurableOutboxFlush(true);
+        }
         return client;
     }
     async close() {
@@ -66,6 +90,7 @@ export class ConductorClient {
             return;
         }
         this.closed = true;
+        this.clearDurableOutboxTimer();
         await this.wsClient.disconnect();
     }
     async createTaskSession(payload) {
@@ -126,6 +151,7 @@ export class ConductorClient {
             throw error;
         }
         await this.waitForTaskCreation(projectId, taskId);
+        this.promoteTaskDeliveryScope(taskId);
         const projectPath = typeof payload.project_path === 'string' && payload.project_path
             ? payload.project_path
             : this.projectPath;
@@ -145,26 +171,32 @@ export class ConductorClient {
         };
     }
     async sendMessage(taskId, content, metadata) {
-        await this.sendEnvelope({
-            type: 'sdk_message',
+        const messageId = safeRandomUuid();
+        const result = await this.persistAndCommitUpstreamEvent({
+            stableId: messageId,
+            eventType: 'sdk_message',
             payload: {
-                task_id: taskId,
+                taskId,
                 content,
                 metadata,
+                messageId,
             },
         });
-        return { delivered: true };
+        return { ...result, message_id: messageId };
     }
     async sendTaskStatus(taskId, payload) {
-        await this.sendEnvelope({
-            type: 'task_status_update',
+        const statusEventId = safeRandomUuid();
+        const result = await this.persistAndCommitUpstreamEvent({
+            stableId: statusEventId,
+            eventType: 'task_status_update',
             payload: {
-                task_id: taskId,
+                taskId,
                 status: payload?.status,
                 summary: payload?.summary,
+                statusEventId,
             },
         });
-        return { delivered: true };
+        return { ...result, status_event_id: statusEventId };
     }
     async sendRuntimeStatus(taskId, payload) {
         await this.sendEnvelope({
@@ -193,6 +225,13 @@ export class ConductorClient {
         return { delivered: true };
     }
     async sendAgentResume(payload = {}) {
+        const storedCursor = this.downstreamCursorStore.get(this.agentHost);
+        const lastAppliedCursor = payload.last_applied_cursor ?? (storedCursor
+            ? {
+                created_at: storedCursor.createdAt,
+                request_id: storedCursor.requestId,
+            }
+            : undefined);
         await this.sendEnvelope({
             type: 'agent_resume',
             payload: {
@@ -201,6 +240,7 @@ export class ConductorClient {
                     : [],
                 source: payload.source,
                 metadata: payload.metadata,
+                last_applied_cursor: lastAppliedCursor,
             },
         });
         return { delivered: true };
@@ -210,16 +250,23 @@ export class ConductorClient {
         if (!requestId) {
             throw new Error('request_id is required');
         }
-        await this.sendEnvelope({
-            type: 'agent_command_ack',
+        const envelopePayload = {
+            request_id: requestId,
+            task_id: payload.task_id,
+            event_type: payload.event_type,
+            accepted: payload.accepted !== false,
+        };
+        const result = await this.persistAndCommitUpstreamEvent({
+            stableId: requestId,
+            eventType: 'agent_command_ack',
             payload: {
-                request_id: requestId,
-                task_id: payload.task_id,
-                event_type: payload.event_type,
-                accepted: payload.accepted !== false,
+                requestId,
+                taskId: envelopePayload.task_id,
+                commandEventType: envelopePayload.event_type,
+                accepted: envelopePayload.accepted,
             },
         });
-        return { delivered: true };
+        return { ...result, request_id: requestId };
     }
     async sendTaskStopAck(payload) {
         const taskId = String(payload.task_id || '').trim();
@@ -230,15 +277,16 @@ export class ConductorClient {
         if (!requestId) {
             throw new Error('request_id is required');
         }
-        await this.sendEnvelope({
-            type: 'task_stop_ack',
+        const result = await this.persistAndCommitUpstreamEvent({
+            stableId: requestId,
+            eventType: 'task_stop_ack',
             payload: {
-                task_id: taskId,
-                request_id: requestId,
+                taskId,
+                requestId,
                 accepted: payload.accepted !== false,
             },
         });
-        return { delivered: true };
+        return { ...result, request_id: requestId, task_id: taskId };
     }
     async receiveMessages(taskId, limit = 20) {
         const messages = await this.sessions.popMessages(taskId, limit);
@@ -326,6 +374,7 @@ export class ConductorClient {
         if (!normalizedTaskId) {
             throw new Error('task_id is required');
         }
+        this.promoteTaskDeliveryScope(normalizedTaskId);
         const existing = this.sessionStore.findByTaskId(normalizedTaskId);
         const inMemorySession = await this.sessions.getSession(normalizedTaskId);
         const projectId = existing?.projectId ||
@@ -418,49 +467,74 @@ export class ConductorClient {
         };
     }
     handleBackendEvent = async (payload) => {
-        const stopCommandAccepted = await this.handleStopTaskEvent(payload);
-        await this.messageRouter.handleBackendEvent(payload);
+        const command = this.extractDownstreamCommandContext(payload);
+        if (command?.eventType === 'stop_task') {
+            await this.handleStopTaskCommand(payload, command);
+            return;
+        }
+        const alreadyApplied = command ? this.downstreamCursorStore.hasApplied(this.agentHost, command.cursor) : false;
+        if (!alreadyApplied) {
+            await this.messageRouter.handleBackendEvent(payload);
+            if (command) {
+                this.downstreamCursorStore.advance(this.agentHost, command.cursor);
+            }
+        }
         await this.maybeAckInboundCommand(payload, {
-            accepted: typeof stopCommandAccepted === 'boolean'
-                ? stopCommandAccepted
-                : undefined,
+            accepted: true,
         });
     };
-    async sendEnvelope(envelope) {
-        await this.wsClient.sendJson(envelope);
-    }
-    async maybeAckInboundCommand(payload, options = {}) {
+    extractDownstreamCommandContext(payload) {
         const eventType = typeof payload?.type === 'string' ? payload.type : '';
         if (eventType !== 'task_user_message' && eventType !== 'task_action' && eventType !== 'stop_task') {
-            return;
+            return null;
         }
         const data = payload?.payload && typeof payload.payload === 'object'
             ? payload.payload
             : null;
         if (!data) {
-            return;
+            return null;
         }
+        const taskId = typeof data.task_id === 'string' ? data.task_id.trim() : '';
         const requestId = typeof data.request_id === 'string' ? data.request_id.trim() : '';
-        if (!requestId) {
+        const cursor = normalizeDownstreamCommandCursor(data.delivery_cursor);
+        if (!taskId || !requestId || !cursor) {
+            return null;
+        }
+        return {
+            eventType,
+            taskId,
+            requestId,
+            cursor,
+        };
+    }
+    async handleStopTaskCommand(payload, command) {
+        const alreadyApplied = this.downstreamCursorStore.hasApplied(this.agentHost, command.cursor);
+        let accepted = false;
+        if (alreadyApplied) {
+            accepted = true;
+        }
+        else {
+            accepted = await this.invokeStopTaskHandler(payload);
+            if (accepted) {
+                this.downstreamCursorStore.advance(this.agentHost, command.cursor);
+            }
+        }
+        if (!command.requestId) {
             return;
         }
         try {
-            await this.sendAgentCommandAck({
-                request_id: requestId,
-                task_id: typeof data.task_id === 'string' ? data.task_id : undefined,
-                event_type: eventType,
-                accepted: typeof options.accepted === 'boolean' ? options.accepted : true,
+            await this.sendTaskStopAck({
+                task_id: command.taskId,
+                request_id: command.requestId,
+                accepted,
             });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            console.warn(`[sdk] failed to ack inbound command ${requestId}: ${message}`);
+            console.warn(`[sdk] failed to send task_stop_ack for task ${command.taskId}: ${message}`);
         }
     }
-    async handleStopTaskEvent(payload) {
-        if (typeof payload?.type !== 'string' || payload.type !== 'stop_task') {
-            return undefined;
-        }
+    async invokeStopTaskHandler(payload) {
         const data = payload?.payload && typeof payload.payload === 'object'
             ? payload.payload
             : null;
@@ -473,35 +547,250 @@ export class ConductorClient {
         if (!taskId) {
             return false;
         }
-        let accepted = false;
-        if (this.onStopTask) {
-            try {
-                await this.onStopTask({
-                    taskId,
-                    requestId: requestId || undefined,
-                    reason: reason || undefined,
-                });
-                accepted = true;
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                console.warn(`[sdk] stop_task callback failed for task ${taskId}: ${message}`);
+        if (!this.onStopTask) {
+            return false;
+        }
+        try {
+            await this.onStopTask({
+                taskId,
+                requestId: requestId || undefined,
+                reason: reason || undefined,
+            });
+            return true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[sdk] stop_task callback failed for task ${taskId}: ${message}`);
+            return false;
+        }
+    }
+    async persistAndCommitUpstreamEvent(entry) {
+        const stored = this.upstreamOutbox.upsert(entry);
+        if (stored.eventType === 'sdk_message' && this.hasEarlierPendingSdkMessage(stored.stableId)) {
+            this.scheduleDurableOutboxFlush(0);
+            return { delivered: false, pending: true };
+        }
+        try {
+            await this.commitDurableUpstreamEvent(stored);
+            this.upstreamOutbox.remove(stored.stableId);
+            return { delivered: true };
+        }
+        catch (error) {
+            if (!this.isRetryableUpstreamError(error)) {
+                this.upstreamOutbox.remove(stored.stableId);
+                throw error;
             }
+            const updated = this.upstreamOutbox.markRetry(stored.stableId, this.computeDurableOutboxRetryDelay(stored.attemptCount + 1));
+            const delay = updated?.nextAttemptAt
+                ? Math.max(Date.parse(updated.nextAttemptAt) - Date.now(), 0)
+                : this.computeDurableOutboxRetryDelay(stored.attemptCount + 1);
+            console.warn(`[sdk] queued ${stored.eventType} (${stored.stableId}) for durable retry after HTTP failure: ${error instanceof Error ? error.message : String(error)}`);
+            this.scheduleDurableOutboxFlush(delay);
+            return { delivered: false, pending: true };
         }
-        if (requestId) {
-            try {
-                await this.sendTaskStopAck({
-                    task_id: taskId,
-                    request_id: requestId,
-                    accepted,
-                });
+    }
+    async requestDurableOutboxFlush(force = false) {
+        if (this.closed) {
+            return;
+        }
+        if (this.durableOutboxFlushPromise) {
+            return this.durableOutboxFlushPromise;
+        }
+        this.durableOutboxFlushPromise = (async () => {
+            const readyEntries = force ? this.upstreamOutbox.load() : this.upstreamOutbox.listReady();
+            let sdkMessageBlocked = false;
+            for (const entry of readyEntries) {
+                if (this.closed) {
+                    break;
+                }
+                if (sdkMessageBlocked && entry.eventType === 'sdk_message') {
+                    continue;
+                }
+                try {
+                    await this.commitDurableUpstreamEvent(entry);
+                    this.upstreamOutbox.remove(entry.stableId);
+                }
+                catch (error) {
+                    if (!this.isRetryableUpstreamError(error)) {
+                        this.upstreamOutbox.remove(entry.stableId);
+                        console.warn(`[sdk] dropping durable upstream event ${entry.eventType} (${entry.stableId}) after terminal HTTP failure: ${error instanceof Error ? error.message : String(error)}`);
+                        continue;
+                    }
+                    const updated = this.upstreamOutbox.markRetry(entry.stableId, this.computeDurableOutboxRetryDelay(entry.attemptCount + 1));
+                    console.warn(`[sdk] durable retry failed for ${entry.eventType} (${entry.stableId}): ${error instanceof Error ? error.message : String(error)}`);
+                    if (entry.eventType === 'sdk_message') {
+                        sdkMessageBlocked = true;
+                    }
+                    if (updated?.nextAttemptAt) {
+                        this.scheduleDurableOutboxFlush(Math.max(Date.parse(updated.nextAttemptAt) - Date.now(), 0));
+                    }
+                }
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                console.warn(`[sdk] failed to send task_stop_ack for task ${taskId}: ${message}`);
+            const nextDelay = this.upstreamOutbox.nextRetryDelay();
+            if (nextDelay !== null) {
+                this.scheduleDurableOutboxFlush(nextDelay);
             }
+        })().finally(() => {
+            this.durableOutboxFlushPromise = null;
+        });
+        return this.durableOutboxFlushPromise;
+    }
+    hasEarlierPendingSdkMessage(stableId) {
+        const entries = this.upstreamOutbox.load();
+        const currentIndex = entries.findIndex((candidate) => candidate.stableId === stableId);
+        if (currentIndex <= 0) {
+            return false;
         }
-        return accepted;
+        return entries.slice(0, currentIndex).some((candidate) => candidate.eventType === 'sdk_message');
+    }
+    async commitDurableUpstreamEvent(entry) {
+        if (entry.eventType === 'sdk_message') {
+            await this.backendApi.commitSdkMessage({
+                agentHost: this.agentHost,
+                taskId: String(entry.payload.taskId || ''),
+                content: String(entry.payload.content || ''),
+                metadata: entry.payload.metadata && typeof entry.payload.metadata === 'object' && !Array.isArray(entry.payload.metadata)
+                    ? entry.payload.metadata
+                    : undefined,
+                messageId: entry.payload.messageId ? String(entry.payload.messageId) : null,
+            });
+            return;
+        }
+        if (entry.eventType === 'task_status_update') {
+            await this.backendApi.commitTaskStatusUpdate({
+                agentHost: this.agentHost,
+                taskId: String(entry.payload.taskId || ''),
+                status: String(entry.payload.status || ''),
+                summary: entry.payload.summary ? String(entry.payload.summary) : null,
+                statusEventId: entry.payload.statusEventId ? String(entry.payload.statusEventId) : null,
+            });
+            return;
+        }
+        if (entry.eventType === 'task_stop_ack') {
+            await this.backendApi.commitTaskStopAck({
+                agentHost: this.agentHost,
+                taskId: String(entry.payload.taskId || ''),
+                requestId: String(entry.payload.requestId || ''),
+                accepted: entry.payload.accepted !== false,
+            });
+            return;
+        }
+        await this.backendApi.commitAgentCommandAck({
+            agentHost: this.agentHost,
+            requestId: String(entry.payload.requestId || ''),
+            taskId: entry.payload.taskId ? String(entry.payload.taskId) : null,
+            accepted: entry.payload.accepted !== false,
+            commandEventType: entry.payload.commandEventType ? String(entry.payload.commandEventType) : null,
+        });
+    }
+    isRetryableUpstreamError(error) {
+        if (!(error instanceof BackendApiError)) {
+            return true;
+        }
+        if (error.statusCode === undefined || error.statusCode === null) {
+            return true;
+        }
+        if (error.statusCode >= 500) {
+            return true;
+        }
+        return error.statusCode === 408 || error.statusCode === 429;
+    }
+    computeDurableOutboxRetryDelay(attemptCount) {
+        const cappedExponent = Math.max(0, Math.min(attemptCount - 1, 5));
+        return 1_000 * 2 ** cappedExponent;
+    }
+    scheduleDurableOutboxFlush(delayMs) {
+        if (this.closed) {
+            return;
+        }
+        const normalizedDelay = Math.max(delayMs, 0);
+        const dueAt = Date.now() + normalizedDelay;
+        if (this.durableOutboxTimer &&
+            this.durableOutboxTimerDueAt !== null &&
+            this.durableOutboxTimerDueAt <= dueAt) {
+            return;
+        }
+        this.clearDurableOutboxTimer();
+        this.durableOutboxTimerDueAt = dueAt;
+        this.durableOutboxTimer = setTimeout(() => {
+            this.durableOutboxTimer = null;
+            this.durableOutboxTimerDueAt = null;
+            void this.requestDurableOutboxFlush(false);
+        }, normalizedDelay);
+    }
+    clearDurableOutboxTimer() {
+        if (this.durableOutboxTimer) {
+            clearTimeout(this.durableOutboxTimer);
+            this.durableOutboxTimer = null;
+        }
+        this.durableOutboxTimerDueAt = null;
+    }
+    async sendEnvelope(envelope) {
+        await this.wsClient.sendJson(envelope);
+    }
+    async maybeAckInboundCommand(payload, options = {}) {
+        const eventType = typeof payload?.type === 'string' ? payload.type : '';
+        if (eventType !== 'task_user_message' && eventType !== 'task_action') {
+            return;
+        }
+        const data = payload?.payload && typeof payload.payload === 'object'
+            ? payload.payload
+            : null;
+        if (!data) {
+            return;
+        }
+        const requestId = typeof data.request_id === 'string' ? data.request_id.trim() : '';
+        if (!requestId) {
+            return;
+        }
+        try {
+            await this.sendAgentCommandAck({
+                request_id: requestId,
+                task_id: typeof data.task_id === 'string' ? data.task_id : undefined,
+                event_type: eventType,
+                accepted: typeof options.accepted === 'boolean' ? options.accepted : true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[sdk] failed to ack inbound command ${requestId}: ${message}`);
+        }
+    }
+    promoteTaskDeliveryScope(taskId) {
+        const normalizedTaskId = String(taskId || '').trim();
+        if (!normalizedTaskId) {
+            return;
+        }
+        this.setDeliveryScopeId(`task:${normalizedTaskId}`);
+    }
+    setDeliveryScopeId(scopeId) {
+        const nextScopeId = normalizeDeliveryScopeId(scopeId);
+        if (nextScopeId === this.deliveryScopeId) {
+            return;
+        }
+        const currentUpstream = this.upstreamOutbox;
+        const currentCursorStore = this.downstreamCursorStore;
+        const nextUpstream = DurableUpstreamOutboxStore.forProjectPath(this.projectPath, nextScopeId);
+        const nextCursorStore = DownstreamCursorStore.forProjectPath(this.projectPath, nextScopeId);
+        for (const entry of currentUpstream.load()) {
+            nextUpstream.upsert({
+                stableId: entry.stableId,
+                eventType: entry.eventType,
+                payload: entry.payload,
+            });
+            currentUpstream.remove(entry.stableId);
+        }
+        const currentCursor = currentCursorStore.get(this.agentHost);
+        if (currentCursor && !nextCursorStore.get(this.agentHost)) {
+            nextCursorStore.advance(this.agentHost, currentCursor);
+        }
+        this.upstreamOutbox = nextUpstream;
+        this.downstreamCursorStore = nextCursorStore;
+        this.deliveryScopeId = nextScopeId;
+        void this.requestDurableOutboxFlush(true);
+    }
+    shouldAutoFlushDurableOutbox() {
+        return this.deliveryScopeId.startsWith('task:') || this.deliveryScopeId.startsWith('session:');
     }
     resolveHostname() {
         const records = this.sessionStore.load();
@@ -580,3 +869,7 @@ function resolveAgentHost(env, explicit) {
     const host = env.HOSTNAME || env.COMPUTERNAME || 'unknown-host';
     return `conductor-fire-${host}-${pid}`;
 }
+function normalizeDeliveryScopeId(scopeId) {
+    const normalized = String(scopeId || '').trim();
+    return normalized || 'default';
+}

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/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/ws/client.d.ts

@@ -21,6 +21,7 @@ export interface WebSocketClientOptions {
         isReconnect: boolean;
     }) => void;
     onDisconnected?: () => void;
+    onReconnected?: () => void;
 }
 export declare class ConductorWebSocketClient {
     private readonly url;
@@ -30,6 +31,7 @@ export declare class ConductorWebSocketClient {
     private readonly connectImpl;
     private readonly onConnected?;
     private readonly onDisconnected?;
+    private readonly onReconnected?;
     private readonly handlers;
     private readonly extraHeaders;
     private conn;
@@ -52,6 +54,7 @@ export declare class ConductorWebSocketClient {
     private handleConnectionLoss;
     private dispatch;
     private notifyConnected;
+    private notifyReconnected;
     private notifyDisconnected;
     private isConnectionClosed;
     private sendWithReconnect;

package/dist/ws/client.js

@@ -16,6 +16,7 @@ export class ConductorWebSocketClient {
     connectImpl;
     onConnected;
     onDisconnected;
+    onReconnected;
     handlers = [];
     extraHeaders;
     conn = null;
@@ -37,6 +38,7 @@ export class ConductorWebSocketClient {
         this.connectImpl = options.connectImpl ?? defaultConnectImpl;
         this.onConnected = options.onConnected;
         this.onDisconnected = options.onDisconnected;
+        this.onReconnected = options.onReconnected;
     }
     registerHandler(handler) {
         this.handlers.push(handler);
@@ -85,6 +87,9 @@ export class ConductorWebSocketClient {
                     const isReconnect = this.hasConnectedAtLeastOnce;
                     this.hasConnectedAtLeastOnce = true;
                     this.notifyConnected(isReconnect);
+                    if (isReconnect) {
+                        this.notifyReconnected();
+                    }
                     this.listenTask = this.listenLoop(this.conn);
                     this.heartbeatTask = this.heartbeatLoop(this.conn);
                     return;
@@ -165,6 +170,17 @@ export class ConductorWebSocketClient {
             // Swallow callback errors to avoid impacting reconnect behavior.
         }
     }
+    notifyReconnected() {
+        if (!this.onReconnected) {
+            return;
+        }
+        try {
+            this.onReconnected();
+        }
+        catch {
+            // Swallow callback errors to avoid impacting reconnect behavior.
+        }
+    }
     notifyDisconnected() {
         if (!this.onDisconnected) {
             return;

package/package.json

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