@love-moon/conductor-sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @love-moon/conductor-sdk
 
+## 0.10.0
+
+### Minor Changes
+
+- 43c4f87: Runtime health preflight and agent schedule access control. The daemon now
+  advertises positive backend runtime health (`x-conductor-runtime-health`) so the
+  backend can reject task creation with `503 runtime_unavailable` before any
+  timeline activity, and adds `disable_built_in_cli_list` to opt out of built-in
+  SDK backends. The SDK attributes agent-originated scheduled-message calls with
+  `X-Conductor-Actor: agent` so per-task `agent_schedule_access`
+  (full/read_only/blocked) can govern `conductor task schedule` from agents while
+  human/UI calls stay unrestricted.
+
+## 0.9.0
+
+### Minor Changes
+
+- a15b55d: Add per-turn multi-image and local context-file inputs, plus authenticated attachment materialization from Conductor Web to the executing daemon.
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/agent-host.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Build the WebSocket identity of a fire process.
+ *
+ * Two properties are load-bearing:
+ *
+ * 1. It must be identical across restarts of the same task. The server pins
+ *    undelivered commands to `agentOutbox.agentHost` and signs attachment
+ *    transfer tokens against this exact string, so a per-process identity
+ *    strands anything still in flight when the process dies.
+ * 2. It must stay unique per concurrent fire. One daemon runs a fire per task
+ *    and the realtime hub evicts an existing connection that reuses a name, so
+ *    a shared identity would make each new fire kick the previous one offline.
+ *
+ * The `conductor-fire-` prefix is also meaningful: it selects the `manual_fire`
+ * plan bucket and keeps fire hosts out of daemon task routing.
+ */
+export declare function buildFireHostName(env: Record<string, string | undefined>, pid?: number): string;

package/dist/agent-host.js

@@ -0,0 +1,32 @@
+const FIRE_HOST_PREFIX = 'conductor-fire-';
+const firstNonEmpty = (...values) => {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return null;
+};
+const sanitizeHostSegment = (value) => value.replace(/[^A-Za-z0-9._-]+/g, '-');
+/**
+ * Build the WebSocket identity of a fire process.
+ *
+ * Two properties are load-bearing:
+ *
+ * 1. It must be identical across restarts of the same task. The server pins
+ *    undelivered commands to `agentOutbox.agentHost` and signs attachment
+ *    transfer tokens against this exact string, so a per-process identity
+ *    strands anything still in flight when the process dies.
+ * 2. It must stay unique per concurrent fire. One daemon runs a fire per task
+ *    and the realtime hub evicts an existing connection that reuses a name, so
+ *    a shared identity would make each new fire kick the previous one offline.
+ *
+ * The `conductor-fire-` prefix is also meaningful: it selects the `manual_fire`
+ * plan bucket and keeps fire hosts out of daemon task routing.
+ */
+export function buildFireHostName(env, pid = process.pid) {
+    const owner = firstNonEmpty(env.CONDUCTOR_DAEMON_NAME, env.HOSTNAME, env.COMPUTERNAME) ?? 'unknown-host';
+    // Before a task exists there is nothing durable to key on, so an unattached
+    // fire keeps a per-process name until it owns a task.
+    const scope = firstNonEmpty(env.CONDUCTOR_TASK_ID) ?? `pid-${pid}`;
+    return `${FIRE_HOST_PREFIX}${sanitizeHostSegment(owner)}-${sanitizeHostSegment(scope)}`;
+}

package/dist/attachments/index.d.ts

@@ -0,0 +1 @@
+export * from './materializer.js';

package/dist/attachments/index.js

@@ -0,0 +1 @@
+export * from './materializer.js';

package/dist/attachments/materializer.d.ts

@@ -0,0 +1,28 @@
+import { ConductorConfig } from '../config/index.js';
+type FetchLike = typeof fetch;
+type JsonRecord = Record<string, unknown>;
+export interface AttachmentMaterializerOptions {
+    config: ConductorConfig;
+    projectPath: string;
+    agentHost: string;
+    fetchImpl?: FetchLike;
+    transferTimeoutMs?: number;
+}
+export declare class AttachmentMaterializer {
+    private readonly config;
+    private readonly projectPath;
+    private readonly agentHost;
+    private readonly fetchImpl;
+    private readonly transferTimeoutMs;
+    private readonly inFlight;
+    private readonly shutdownController;
+    constructor(options: AttachmentMaterializerOptions);
+    abortAll(): void;
+    validateEnvelopeForStaging(envelope: JsonRecord): boolean;
+    materializeEnvelope(envelope: JsonRecord): Promise<JsonRecord>;
+    private materializeAttachments;
+    private materializeOne;
+    private reportMaterialized;
+    private fetchWithTimeout;
+}
+export {};

package/dist/attachments/materializer.js

@@ -0,0 +1,258 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+const MAX_ATTACHMENT_BYTES = 100 * 1024 * 1024;
+const MAX_ATTACHMENTS = 20;
+const DEFAULT_TRANSFER_TIMEOUT_MS = 120_000;
+function cleanSegment(value, fallback) {
+    const basename = path.basename(typeof value === 'string' ? value : '').replace(/[^A-Za-z0-9._-]+/g, '-');
+    return basename || fallback;
+}
+function normalizeSha256(value) {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return /^[a-f0-9]{64}$/.test(normalized) ? normalized : '';
+}
+function withoutTransferToken(attachment) {
+    const { transferToken: _transferToken, ...safe } = attachment;
+    return safe;
+}
+function atomicWriteJson(filePath, value) {
+    const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, filePath);
+}
+async function hashFile(filePath) {
+    const hash = crypto.createHash('sha256');
+    for await (const chunk of fs.createReadStream(filePath))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+export class AttachmentMaterializer {
+    config;
+    projectPath;
+    agentHost;
+    fetchImpl;
+    transferTimeoutMs;
+    inFlight = new Map();
+    shutdownController = new AbortController();
+    constructor(options) {
+        this.config = options.config;
+        this.projectPath = path.resolve(options.projectPath);
+        this.agentHost = options.agentHost;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.transferTimeoutMs = options.transferTimeoutMs ?? DEFAULT_TRANSFER_TIMEOUT_MS;
+    }
+    abortAll() {
+        this.shutdownController.abort(new Error('Attachment materializer closed'));
+    }
+    validateEnvelopeForStaging(envelope) {
+        if (envelope.type !== 'task_user_message')
+            return false;
+        const payload = envelope.payload && typeof envelope.payload === 'object' ? envelope.payload : null;
+        if (!payload || !Array.isArray(payload.attachments) || payload.attachments.length === 0)
+            return false;
+        const attachments = payload.attachments;
+        if (attachments.some((entry) => !entry || typeof entry !== 'object' || Array.isArray(entry)
+            || !normalizeSha256(entry.sha256)))
+            return false;
+        if (attachments.length > MAX_ATTACHMENTS)
+            throw new Error('Too many message attachments');
+        const ids = attachments.map((entry) => typeof entry.id === 'string'
+            ? String(entry.id).trim() : '');
+        if (ids.some((id) => !id) || new Set(ids).size !== ids.length)
+            throw new Error('Message attachments must have unique IDs');
+        for (const raw of attachments) {
+            const size = typeof raw.sizeBytes === 'number' ? raw.sizeBytes : Number.NaN;
+            const transferToken = typeof raw.transferToken === 'string' ? raw.transferToken.trim() : '';
+            if (!transferToken || (raw.kind !== 'image' && raw.kind !== 'file') || !Number.isSafeInteger(size) || size < 0 || size > MAX_ATTACHMENT_BYTES) {
+                throw new Error(`Invalid attachment descriptor for ${String(raw.id || 'attachment')}`);
+            }
+        }
+        const taskId = typeof payload.task_id === 'string' ? payload.task_id.trim() : '';
+        const messageId = typeof payload.message_id === 'string' ? payload.message_id.trim() : '';
+        if (!taskId || !messageId)
+            throw new Error('Attachment message is missing task_id or message_id');
+        return true;
+    }
+    async materializeEnvelope(envelope) {
+        if (envelope.type !== 'task_user_message')
+            return envelope;
+        const payload = envelope.payload && typeof envelope.payload === 'object'
+            ? { ...envelope.payload }
+            : null;
+        if (!payload || !Array.isArray(payload.attachments) || payload.attachments.length === 0)
+            return envelope;
+        const attachments = payload.attachments;
+        // Attachments created before the reliable-transfer protocol did not carry a
+        // digest. Preserve those legacy display-only descriptors instead of
+        // turning an old message into a permanently unacknowledgeable command.
+        if (payload.attachments.some((entry) => !entry || typeof entry !== 'object' || Array.isArray(entry) || !normalizeSha256(entry.sha256)))
+            return envelope;
+        if (payload.attachments.length > MAX_ATTACHMENTS)
+            throw new Error('Too many message attachments');
+        const attachmentIds = payload.attachments.map((entry) => typeof entry.id === 'string' ? String(entry.id).trim() : '');
+        if (attachmentIds.some((id) => !id) || new Set(attachmentIds).size !== attachmentIds.length) {
+            throw new Error('Message attachments must have unique IDs');
+        }
+        const taskId = typeof payload.task_id === 'string' ? payload.task_id.trim() : '';
+        const messageId = typeof payload.message_id === 'string' ? payload.message_id.trim() : '';
+        if (!taskId || !messageId)
+            throw new Error('Attachment message is missing task_id or message_id');
+        const key = `${taskId}:${messageId}`;
+        const current = this.inFlight.get(key);
+        if (current)
+            return current;
+        const operation = this.materializeAttachments(envelope, payload, attachments, taskId, messageId);
+        this.inFlight.set(key, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            this.inFlight.delete(key);
+        }
+    }
+    async materializeAttachments(envelope, payload, attachments, taskId, messageId) {
+        const messageDir = path.join(this.projectPath, '.conductor', 'attachments', cleanSegment(messageId, 'message'));
+        fs.mkdirSync(messageDir, { recursive: true, mode: 0o700 });
+        const manifestPath = path.join(messageDir, 'manifest.json');
+        atomicWriteJson(manifestPath, {
+            taskId,
+            messageId,
+            status: 'materializing',
+            attachments: attachments.map((entry) => withoutTransferToken(entry)),
+            updatedAt: new Date().toISOString(),
+        });
+        const localAttachments = [];
+        for (const raw of attachments) {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error('Invalid attachment descriptor');
+            localAttachments.push(await this.materializeOne(taskId, messageDir, raw));
+        }
+        atomicWriteJson(manifestPath, {
+            taskId,
+            messageId,
+            status: 'ready',
+            attachments: localAttachments,
+            updatedAt: new Date().toISOString(),
+        });
+        await this.reportMaterialized(taskId, messageId, localAttachments, attachments);
+        const metadata = payload.metadata && typeof payload.metadata === 'object' && !Array.isArray(payload.metadata)
+            ? { ...payload.metadata, attachments: localAttachments }
+            : { attachments: localAttachments };
+        return { ...envelope, payload: { ...payload, metadata, attachments: localAttachments } };
+    }
+    async materializeOne(taskId, messageDir, attachment) {
+        const id = typeof attachment.id === 'string' ? attachment.id.trim() : '';
+        const name = cleanSegment(attachment.name, 'attachment');
+        const sha256 = normalizeSha256(attachment.sha256);
+        const sizeBytes = typeof attachment.sizeBytes === 'number' ? attachment.sizeBytes : Number.NaN;
+        const kind = attachment.kind === 'image' ? 'image' : attachment.kind === 'file' ? 'file' : '';
+        if (!id || !sha256 || !kind || !Number.isSafeInteger(sizeBytes) || sizeBytes < 0 || sizeBytes > MAX_ATTACHMENT_BYTES) {
+            throw new Error(`Invalid attachment descriptor for ${id || name}`);
+        }
+        const localPath = path.join(messageDir, `${cleanSegment(id, 'attachment')}--${name}`);
+        if (fs.existsSync(localPath)) {
+            const stat = fs.statSync(localPath);
+            if (stat.isFile() && stat.size === sizeBytes && await hashFile(localPath) === sha256) {
+                return { ...withoutTransferToken(attachment), path: localPath, localPath, status: 'ready' };
+            }
+            fs.rmSync(localPath, { force: true });
+        }
+        const url = new URL(`/api/agent/tasks/${encodeURIComponent(taskId)}/attachments/${encodeURIComponent(id)}/content`, this.config.backendUrl);
+        const transferToken = typeof attachment.transferToken === 'string' ? attachment.transferToken.trim() : '';
+        if (!transferToken)
+            throw new Error(`Attachment transfer token missing for ${id}`);
+        const transferHeaders = {
+            Authorization: `Bearer ${this.config.agentToken}`,
+            'X-Conductor-Host': this.agentHost,
+            'X-Conductor-Attachment-Token': transferToken,
+            Accept: 'application/octet-stream',
+        };
+        const transferSignal = AbortSignal.any([
+            AbortSignal.timeout(this.transferTimeoutMs),
+            this.shutdownController.signal,
+        ]);
+        const response = await this.fetchImpl(url, {
+            headers: transferHeaders,
+            signal: transferSignal,
+        });
+        if (!response.ok || !response.body) {
+            const error = new Error(`Attachment download failed with HTTP ${response.status}`);
+            // The attachment was released, deleted or is no longer readable by this
+            // host. Retrying cannot fix that, so let the caller stop instead of
+            // looping on a 404 until the process dies.
+            if (response.status === 403 || response.status === 404 || response.status === 410)
+                error.permanent = true;
+            throw error;
+        }
+        const contentLength = response.headers.get('content-length');
+        const declaredLength = contentLength === null ? null : Number(contentLength);
+        if (declaredLength !== null && Number.isFinite(declaredLength) && declaredLength !== sizeBytes) {
+            throw new Error('Attachment Content-Length mismatch');
+        }
+        const temporaryPath = `${localPath}.${process.pid}.${crypto.randomUUID()}.part`;
+        const hash = crypto.createHash('sha256');
+        let received = 0;
+        const verifier = new Transform({
+            transform(chunk, _encoding, callback) {
+                received += chunk.length;
+                if (received > sizeBytes || received > MAX_ATTACHMENT_BYTES) {
+                    callback(new Error('Attachment exceeded declared size'));
+                    return;
+                }
+                hash.update(chunk);
+                callback(null, chunk);
+            },
+        });
+        try {
+            await pipeline(Readable.fromWeb(response.body), verifier, fs.createWriteStream(temporaryPath, { mode: 0o600 }), { signal: transferSignal });
+            if (received !== sizeBytes)
+                throw new Error('Attachment size mismatch');
+            if (hash.digest('hex') !== sha256)
+                throw new Error('Attachment SHA-256 mismatch');
+            fs.renameSync(temporaryPath, localPath);
+        }
+        catch (error) {
+            fs.rmSync(temporaryPath, { force: true });
+            throw error;
+        }
+        return { ...withoutTransferToken(attachment), path: localPath, localPath, status: 'ready' };
+    }
+    async reportMaterialized(taskId, messageId, attachments, sourceAttachments) {
+        const url = new URL(`/api/agent/tasks/${encodeURIComponent(taskId)}/messages/${encodeURIComponent(messageId)}/materialized`, this.config.backendUrl);
+        const response = await this.fetchWithTimeout(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.config.agentToken}`,
+                'X-Conductor-Host': this.agentHost,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                attachments: attachments.map((attachment, index) => ({
+                    id: attachment.id,
+                    sha256: attachment.sha256,
+                    status: 'ready',
+                    transferToken: sourceAttachments[index]?.transferToken,
+                })),
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`Attachment materialization report failed with HTTP ${response.status}`);
+    }
+    async fetchWithTimeout(input, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error('Attachment transfer timed out')), this.transferTimeoutMs);
+        const abortForShutdown = () => controller.abort(this.shutdownController.signal.reason);
+        this.shutdownController.signal.addEventListener('abort', abortForShutdown, { once: true });
+        timeout.unref?.();
+        try {
+            return await this.fetchImpl(input, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timeout);
+            this.shutdownController.signal.removeEventListener('abort', abortForShutdown);
+        }
+    }
+}

package/dist/backend/client.js

@@ -1,3 +1,15 @@
+/**
+ * Mark a request as originating from an autonomous agent turn. The daemon
+ * exports `CONDUCTOR_LAUNCHED_BY_DAEMON=1` into the fire process (and the shell
+ * commands it runs), so any scheduling call made while the AI is driving the
+ * turn is attributed to the agent. The backend uses this to enforce the
+ * per-task agent schedule access level; ordinary human/app calls omit it and
+ * are never restricted.
+ */
+function agentActorHeaders() {
+    const launchedByDaemon = typeof process !== 'undefined' && process.env?.CONDUCTOR_LAUNCHED_BY_DAEMON === '1';
+    return launchedByDaemon ? { 'X-Conductor-Actor': 'agent' } : {};
+}
 export class BackendApiError extends Error {
     statusCode;
     details;
@@ -463,7 +475,9 @@ export class BackendApiClient {
         return this.parseJson(response);
     }
     async listScheduledMessages(taskId) {
-        const response = await this.request('GET', `/tasks/${taskId}/scheduled-messages`);
+        const response = await this.request('GET', `/tasks/${taskId}/scheduled-messages`, {
+            headers: agentActorHeaders(),
+        });
         const payload = await this.parseJson(response);
         if (payload && typeof payload === 'object' && Array.isArray(payload.schedules)) {
             return payload.schedules;
@@ -476,22 +490,25 @@ export class BackendApiClient {
     async createScheduledMessage(taskId, params) {
         const response = await this.request('POST', `/tasks/${taskId}/scheduled-messages`, {
             body: JSON.stringify(params),
+            headers: agentActorHeaders(),
         });
         return this.parseJson(response);
     }
     async deleteScheduledMessage(taskId, scheduleId) {
-        await this.request('DELETE', `/tasks/${taskId}/scheduled-messages/${scheduleId}`);
+        await this.request('DELETE', `/tasks/${taskId}/scheduled-messages/${scheduleId}`, {
+            headers: agentActorHeaders(),
+        });
     }
     async request(method, pathname, opts = {}) {
         const url = this.buildUrl(pathname, opts.query);
         const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
         const timeout = controller ? setTimeout(() => controller.abort(), this.timeoutMs) : null;
         try {
-            let response = await this.sendRequest(url, method, opts.body, controller);
+            let response = await this.sendRequest(url, method, opts.body, controller, opts.headers);
             if (response.status === 404 &&
                 this.shouldRetryWithApiPrefix(pathname, url)) {
                 const retryUrl = this.buildUrl(this.withApiPrefix(pathname), opts.query);
-                response = await this.sendRequest(retryUrl, method, opts.body, controller);
+                response = await this.sendRequest(retryUrl, method, opts.body, controller, opts.headers);
             }
             if (!response.ok) {
                 const details = await this.safeJson(response);
@@ -518,13 +535,14 @@ export class BackendApiClient {
         }
         return url;
     }
-    async sendRequest(url, method, body, controller) {
+    async sendRequest(url, method, body, controller, extraHeaders) {
         return this.fetchImpl(url.toString(), {
             method,
             headers: {
                 Authorization: `Bearer ${this.config.agentToken}`,
                 Accept: 'application/json',
                 ...(body ? { 'Content-Type': 'application/json' } : {}),
+                ...(extraHeaders ?? {}),
             },
             body,
             signal: controller?.signal,

package/dist/client.d.ts

@@ -1,7 +1,8 @@
 import { BackendApiClient } from './backend/index.js';
+import { AttachmentMaterializer } from './attachments/index.js';
 import { ConductorConfig } from './config/index.js';
 import { MessageRouter } from './message/index.js';
-import { DownstreamCursorStore, DurableUpstreamOutboxStore } from './outbox/index.js';
+import { DownstreamInboxStore, DownstreamCursorStore, DurableUpstreamOutboxStore } from './outbox/index.js';
 import { SessionDiskStore, SessionManager } from './session/index.js';
 import { ConductorWebSocketClient, WebSocketConnectedEvent, WebSocketDisconnectEvent, WebSocketPongEvent } from './ws/index.js';
 type BackendApiLike = Pick<BackendApiClient, 'listProjects' | 'createProject' | 'listTasks' | 'getTask' | 'createTask' | 'updateTask' | 'commitSdkMessage' | 'commitTaskStatusUpdate' | 'commitAgentCommandAck' | 'commitTaskStopAck' | 'matchProjectByPath' | 'getProject' | 'updateProject'>;
@@ -20,6 +21,8 @@ export interface ConductorClientConnectOptions {
     messageRouter?: MessageRouter;
     upstreamOutbox?: DurableUpstreamOutboxStore;
     downstreamCursorStore?: DownstreamCursorStore;
+    downstreamInboxStore?: DownstreamInboxStore;
+    attachmentMaterializer?: AttachmentMaterializer;
     agentHost?: string;
     extraHeaders?: Record<string, string>;
     onConnected?: (event: WebSocketConnectedEvent) => void;
@@ -41,6 +44,8 @@ interface ConductorClientInit {
     messageRouter: MessageRouter;
     upstreamOutbox: DurableUpstreamOutboxStore;
     downstreamCursorStore: DownstreamCursorStore;
+    downstreamInboxStore: DownstreamInboxStore;
+    attachmentMaterializer: AttachmentMaterializer;
     agentHost: string;
     onStopTask?: (event: StopTaskEvent) => Promise<void> | void;
     onInterruptTurn?: (event: InterruptTurnEvent) => Promise<boolean | void> | boolean | void;
@@ -79,6 +84,8 @@ export declare class ConductorClient {
     private readonly messageRouter;
     private upstreamOutbox;
     private downstreamCursorStore;
+    private downstreamInboxStore;
+    private readonly attachmentMaterializer;
     private readonly agentHost;
     private readonly onStopTask?;
     private readonly onInterruptTurn?;
@@ -88,6 +95,11 @@ export declare class ConductorClient {
     private durableOutboxFlushPromise;
     private durableOutboxTimer;
     private durableOutboxTimerDueAt;
+    private readonly downstreamTasks;
+    private readonly queuedDownstreamRequests;
+    private readonly cancelledDownstreamTasks;
+    private readonly downstreamWorkerAbort;
+    private downstreamClosing;
     constructor(init: ConductorClientInit);
     static connect(options?: ConductorClientConnectOptions): Promise<ConductorClient>;
     close(): Promise<void>;
@@ -133,6 +145,13 @@ 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 replayDurableDownstreamInbox;
+    private enqueueDurableDownstreamCommand;
+    /**
+     * Tell the user why an attachment message will never run. Silently dropping
+     * it would leave a question in the chat that never gets an answer.
+     */
+    private reportUnrecoverableAttachmentCommand;
     private extractDownstreamCommandContext;
     private handleStopTaskCommand;
     private invokeStopTaskHandler;

package/dist/client.js

@@ -1,15 +1,24 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { buildFireHostName } from './agent-host.js';
 import { BackendApiClient, BackendApiError } from './backend/index.js';
+import { AttachmentMaterializer } from './attachments/index.js';
 import { loadConfig } from './config/index.js';
 import { ProjectContext } from './context/index.js';
 import { getPlanLimitMessageFromError } from './limits/index.js';
 import { MessageRouter } from './message/index.js';
-import { DownstreamCursorStore, DurableUpstreamOutboxStore, normalizeDownstreamCommandCursor, } from './outbox/index.js';
+import { DownstreamInboxStore, 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));
+const sleepWithSignal = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        return resolve();
+    const timer = setTimeout(resolve, Math.max(0, ms));
+    timer.unref?.();
+    signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+});
 export class ConductorClient {
     config;
     env;
@@ -21,6 +30,8 @@ export class ConductorClient {
     messageRouter;
     upstreamOutbox;
     downstreamCursorStore;
+    downstreamInboxStore;
+    attachmentMaterializer;
     agentHost;
     onStopTask;
     onInterruptTurn;
@@ -30,6 +41,11 @@ export class ConductorClient {
     durableOutboxFlushPromise = null;
     durableOutboxTimer = null;
     durableOutboxTimerDueAt = null;
+    downstreamTasks = new Map();
+    queuedDownstreamRequests = new Set();
+    cancelledDownstreamTasks = new Set();
+    downstreamWorkerAbort = new AbortController();
+    downstreamClosing = false;
     constructor(init) {
         this.config = init.config;
         this.env = init.env;
@@ -41,6 +57,8 @@ export class ConductorClient {
         this.messageRouter = init.messageRouter;
         this.upstreamOutbox = init.upstreamOutbox;
         this.downstreamCursorStore = init.downstreamCursorStore;
+        this.downstreamInboxStore = init.downstreamInboxStore;
+        this.attachmentMaterializer = init.attachmentMaterializer;
         this.agentHost = init.agentHost;
         this.onStopTask = init.onStopTask;
         this.onInterruptTurn = init.onInterruptTurn;
@@ -60,6 +78,12 @@ export class ConductorClient {
         const deliveryScopeId = normalizeDeliveryScopeId(options.deliveryScopeId ?? `agent:${agentHost}`);
         const upstreamOutbox = options.upstreamOutbox ?? DurableUpstreamOutboxStore.forProjectPath(projectPath, deliveryScopeId);
         const downstreamCursorStore = options.downstreamCursorStore ?? DownstreamCursorStore.forProjectPath(projectPath, deliveryScopeId);
+        const downstreamInboxStore = options.downstreamInboxStore ?? DownstreamInboxStore.forProjectPath(projectPath, deliveryScopeId);
+        const attachmentMaterializer = options.attachmentMaterializer ?? new AttachmentMaterializer({
+            config,
+            projectPath,
+            agentHost,
+        });
         const wsClient = options.wsClient ??
             new ConductorWebSocketClient(config, {
                 hostName: agentHost,
@@ -85,12 +109,23 @@ export class ConductorClient {
             messageRouter,
             upstreamOutbox,
             downstreamCursorStore,
+            downstreamInboxStore,
+            attachmentMaterializer,
             agentHost,
             onStopTask: options.onStopTask,
             onInterruptTurn: options.onInterruptTurn,
             onRefreshSession: options.onRefreshSession,
         });
-        await client.wsClient.connect();
+        client.replayDurableDownstreamInbox();
+        try {
+            await client.wsClient.connect();
+        }
+        catch (error) {
+            client.downstreamClosing = true;
+            client.downstreamWorkerAbort.abort();
+            client.attachmentMaterializer.abortAll();
+            throw error;
+        }
         if (client.shouldAutoFlushDurableOutbox()) {
             void client.requestDurableOutboxFlush(true);
         }
@@ -100,6 +135,9 @@ export class ConductorClient {
         if (this.closed) {
             return;
         }
+        this.downstreamClosing = true;
+        this.downstreamWorkerAbort.abort();
+        this.attachmentMaterializer.abortAll();
         this.clearDurableOutboxTimer();
         await this.flushPendingUpstreamEvents({
             timeoutMs: 2_000,
@@ -576,12 +614,28 @@ export class ConductorClient {
         }
         const command = this.extractDownstreamCommandContext(payload);
         if (command?.eventType === 'stop_task') {
+            this.cancelledDownstreamTasks.add(command.taskId);
             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.attachmentMaterializer.validateEnvelopeForStaging(payload)) {
+                const durable = this.downstreamInboxStore.upsert({
+                    requestId: command.requestId,
+                    taskId: command.taskId,
+                    cursor: command.cursor,
+                    envelope: payload,
+                });
+                this.enqueueDurableDownstreamCommand(durable);
+                await this.maybeAckInboundCommand(payload, { accepted: true });
+                return;
+            }
+            if (command) {
+                await this.downstreamTasks.get(command.taskId);
+            }
+            const materializedPayload = await this.attachmentMaterializer.materializeEnvelope(payload);
+            await this.messageRouter.handleBackendEvent(materializedPayload);
             if (command) {
                 this.downstreamCursorStore.advance(this.agentHost, command.cursor);
             }
@@ -590,6 +644,93 @@ export class ConductorClient {
             accepted: true,
         });
     };
+    replayDurableDownstreamInbox() {
+        const entries = this.downstreamInboxStore.list().sort((left, right) => {
+            const byTime = Date.parse(left.cursor.createdAt) - Date.parse(right.cursor.createdAt);
+            return byTime || left.cursor.requestId.localeCompare(right.cursor.requestId);
+        });
+        for (const entry of entries)
+            this.enqueueDurableDownstreamCommand(entry);
+    }
+    enqueueDurableDownstreamCommand(entry) {
+        if (this.queuedDownstreamRequests.has(entry.requestId))
+            return;
+        this.queuedDownstreamRequests.add(entry.requestId);
+        const previous = this.downstreamTasks.get(entry.taskId) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(async () => {
+            let attempt = entry.attemptCount;
+            while (!this.closed && !this.downstreamClosing) {
+                if (this.cancelledDownstreamTasks.has(entry.taskId)) {
+                    this.downstreamInboxStore.remove(entry.requestId);
+                    return;
+                }
+                const nextAttemptMs = Date.parse(entry.nextAttemptAt);
+                if (Number.isFinite(nextAttemptMs) && nextAttemptMs > Date.now()) {
+                    await sleepWithSignal(nextAttemptMs - Date.now(), this.downstreamWorkerAbort.signal);
+                }
+                try {
+                    const materialized = await this.attachmentMaterializer.materializeEnvelope(entry.envelope);
+                    if (this.cancelledDownstreamTasks.has(entry.taskId)) {
+                        this.downstreamInboxStore.remove(entry.requestId);
+                        return;
+                    }
+                    // A shutdown after download must leave the already-ACKed command in
+                    // the durable inbox so the next process can route it. Removing it
+                    // here would make the Web outbox and the Daemon both forget it.
+                    if (this.closed || this.downstreamClosing)
+                        return;
+                    await this.messageRouter.handleBackendEvent(materialized);
+                    this.downstreamCursorStore.advance(this.agentHost, entry.cursor);
+                    this.downstreamInboxStore.remove(entry.requestId);
+                    return;
+                }
+                catch (error) {
+                    if (error?.permanent) {
+                        const reported = await this.reportUnrecoverableAttachmentCommand(entry, error);
+                        // Only drop the command once the user-facing explanation is durably
+                        // queued; otherwise keep retrying so the failure cannot vanish.
+                        if (reported) {
+                            this.downstreamCursorStore.advance(this.agentHost, entry.cursor);
+                            this.downstreamInboxStore.remove(entry.requestId);
+                            return;
+                        }
+                    }
+                    attempt += 1;
+                    const delayMs = Math.min(1_000 * (2 ** Math.min(attempt, 5)), 30_000);
+                    try {
+                        this.downstreamInboxStore.markRetry(entry.requestId, delayMs);
+                    }
+                    catch (persistError) {
+                        console.warn(`[sdk] failed to persist downstream retry state for ${entry.requestId}: ${persistError instanceof Error ? persistError.message : String(persistError)}`);
+                    }
+                    console.warn(`[sdk] downstream attachment command ${entry.requestId} failed; retrying in ${delayMs}ms: ${error instanceof Error ? error.message : String(error)}`);
+                    await sleepWithSignal(delayMs, this.downstreamWorkerAbort.signal);
+                }
+            }
+        }).catch((error) => {
+            console.warn(`[sdk] downstream worker ${entry.requestId} stopped unexpectedly: ${error instanceof Error ? error.message : String(error)}`);
+        }).finally(() => {
+            this.queuedDownstreamRequests.delete(entry.requestId);
+            if (this.downstreamTasks.get(entry.taskId) === current)
+                this.downstreamTasks.delete(entry.taskId);
+        });
+        this.downstreamTasks.set(entry.taskId, current);
+    }
+    /**
+     * Tell the user why an attachment message will never run. Silently dropping
+     * it would leave a question in the chat that never gets an answer.
+     */
+    async reportUnrecoverableAttachmentCommand(entry, error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        try {
+            await this.sendMessage(entry.taskId, `The attachments on this message are no longer available, so it could not be processed (${reason}). Please send them again.`, { attachment_delivery: 'failed', reply_to: entry.requestId });
+            return true;
+        }
+        catch (reportError) {
+            console.warn(`[sdk] failed to report unrecoverable attachment command ${entry.requestId}: ${reportError instanceof Error ? reportError.message : String(reportError)}`);
+            return false;
+        }
+    }
     extractDownstreamCommandContext(payload) {
         const eventType = typeof payload?.type === 'string' ? payload.type : '';
         if (eventType !== 'task_user_message' && eventType !== 'task_action' && eventType !== 'stop_task') {
@@ -966,8 +1107,10 @@ export class ConductorClient {
         }
         const currentUpstream = this.upstreamOutbox;
         const currentCursorStore = this.downstreamCursorStore;
+        const currentInboxStore = this.downstreamInboxStore;
         const nextUpstream = DurableUpstreamOutboxStore.forProjectPath(this.projectPath, nextScopeId);
         const nextCursorStore = DownstreamCursorStore.forProjectPath(this.projectPath, nextScopeId);
+        const nextInboxStore = DownstreamInboxStore.forProjectPath(this.projectPath, nextScopeId);
         for (const entry of currentUpstream.load()) {
             nextUpstream.upsert({
                 stableId: entry.stableId,
@@ -977,11 +1120,16 @@ export class ConductorClient {
             currentUpstream.remove(entry.stableId);
         }
         const currentCursor = currentCursorStore.get(this.agentHost);
-        if (currentCursor && !nextCursorStore.get(this.agentHost)) {
+        if (currentCursor) {
             nextCursorStore.advance(this.agentHost, currentCursor);
         }
+        for (const entry of currentInboxStore.list()) {
+            nextInboxStore.import(entry);
+            currentInboxStore.remove(entry.requestId);
+        }
         this.upstreamOutbox = nextUpstream;
         this.downstreamCursorStore = nextCursorStore;
+        this.downstreamInboxStore = nextInboxStore;
         this.deliveryScopeId = nextScopeId;
         void this.requestDurableOutboxFlush(true);
     }
@@ -1059,13 +1207,12 @@ function resolveAgentHost(env, explicit) {
     if (typeof fromAgent === 'string' && fromAgent.trim()) {
         return fromAgent.trim();
     }
-    const fromDaemon = env.CONDUCTOR_DAEMON_NAME;
-    if (typeof fromDaemon === 'string' && fromDaemon.trim()) {
-        return fromDaemon.trim();
-    }
-    const pid = process.pid;
-    const host = env.HOSTNAME || env.COMPUTERNAME || 'unknown-host';
-    return `conductor-fire-${host}-${pid}`;
+    // CONDUCTOR_DAEMON_NAME is inherited from the daemon that spawned this fire,
+    // so it names the daemon, not this process. Returning it verbatim would make
+    // the fire impersonate its own daemon: same identity on the hub (mutual
+    // eviction) and no `conductor-fire-` prefix (wrong plan bucket, eligible for
+    // daemon task routing). Use it as the owner segment instead.
+    return buildFireHostName(env);
 }
 function normalizeDeliveryScopeId(scopeId) {
     const normalized = String(scopeId || '').trim();

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './agent-host.js';
 export * from './paths.js';
 export * from './config/index.js';
 export * from './backend/index.js';
@@ -9,3 +10,4 @@ export * from './context/index.js';
 export * from './limits/index.js';
 export * from './outbox/index.js';
 export * from './api/index.js';
+export * from './attachments/index.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './agent-host.js';
 export * from './paths.js';
 export * from './config/index.js';
 export * from './backend/index.js';
@@ -9,3 +10,4 @@ export * from './context/index.js';
 export * from './limits/index.js';
 export * from './outbox/index.js';
 export * from './api/index.js';
+export * from './attachments/index.js';

package/dist/outbox/downstream-inbox-store.d.ts

@@ -0,0 +1,20 @@
+import type { DownstreamCommandCursor } from './downstream-cursor-store.js';
+export interface DurableDownstreamCommand {
+    requestId: string;
+    taskId: string;
+    cursor: DownstreamCommandCursor;
+    envelope: Record<string, unknown>;
+    attemptCount: number;
+    nextAttemptAt: string;
+}
+export declare class DownstreamInboxStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    static forProjectPath(projectPath: string, scopeId: string): DownstreamInboxStore;
+    list(): DurableDownstreamCommand[];
+    upsert(command: Omit<DurableDownstreamCommand, 'attemptCount' | 'nextAttemptAt'>): DurableDownstreamCommand;
+    import(entry: DurableDownstreamCommand): DurableDownstreamCommand;
+    markRetry(requestId: string, delayMs: number): void;
+    remove(requestId: string): void;
+    private save;
+}

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

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const STATE_DIR = path.join('.conductor', 'state');
+const BASENAME = 'agent-downstream-inbox';
+function isDurableCommand(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    return typeof entry.requestId === 'string' && Boolean(entry.requestId.trim())
+        && typeof entry.taskId === 'string' && Boolean(entry.taskId.trim())
+        && Boolean(entry.cursor) && typeof entry.cursor?.createdAt === 'string' && typeof entry.cursor?.requestId === 'string'
+        && Boolean(entry.envelope) && typeof entry.envelope === 'object'
+        && Number.isSafeInteger(entry.attemptCount) && (entry.attemptCount ?? -1) >= 0
+        && typeof entry.nextAttemptAt === 'string';
+}
+const sanitizeScopeId = (value) => value.trim().replace(/[^A-Za-z0-9._-]+/g, '_') || 'default';
+export class DownstreamInboxStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    static forProjectPath(projectPath, scopeId) {
+        return new DownstreamInboxStore(path.join(projectPath, STATE_DIR, `${BASENAME}.${sanitizeScopeId(scopeId)}.json`));
+    }
+    list() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf8'));
+            if (!Array.isArray(parsed.entries))
+                throw new Error(`Invalid downstream inbox: ${this.filePath}`);
+            if (!parsed.entries.every(isDurableCommand))
+                throw new Error(`Invalid downstream inbox entry: ${this.filePath}`);
+            return parsed.entries;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    upsert(command) {
+        const entries = this.list();
+        const existing = entries.find((entry) => entry.requestId === command.requestId);
+        if (existing)
+            return existing;
+        const entry = { ...command, attemptCount: 0, nextAttemptAt: new Date().toISOString() };
+        this.save([...entries, entry]);
+        return entry;
+    }
+    import(entry) {
+        const entries = this.list();
+        const existing = entries.find((candidate) => candidate.requestId === entry.requestId);
+        if (existing)
+            return existing;
+        this.save([...entries, entry]);
+        return entry;
+    }
+    markRetry(requestId, delayMs) {
+        const entries = this.list().map((entry) => entry.requestId === requestId ? {
+            ...entry,
+            attemptCount: entry.attemptCount + 1,
+            nextAttemptAt: new Date(Date.now() + delayMs).toISOString(),
+        } : entry);
+        this.save(entries);
+    }
+    remove(requestId) {
+        this.save(this.list().filter((entry) => entry.requestId !== requestId));
+    }
+    save(entries) {
+        const resolved = path.resolve(this.filePath);
+        const directory = path.dirname(resolved);
+        fs.mkdirSync(directory, { recursive: true });
+        const temporary = `${resolved}.${process.pid}.${Date.now()}.tmp`;
+        const fd = fs.openSync(temporary, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, JSON.stringify({ entries }, null, 2));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, resolved);
+        const directoryFd = fs.openSync(directory, 'r');
+        try {
+            fs.fsyncSync(directoryFd);
+        }
+        finally {
+            fs.closeSync(directoryFd);
+        }
+    }
+}

package/dist/outbox/index.d.ts

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

package/dist/outbox/index.js

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

package/dist/session/manager.d.ts

@@ -25,6 +25,7 @@ export declare class SessionState {
     lastMessageAt: Date;
     status: string;
     pendingMessages: MessageRecord[];
+    readonly seenMessageIds: Set<string>;
     ackToken: string | null;
     constructor(taskId: string, sessionId: string, projectId: string, createdAt?: Date);
 }

package/dist/session/manager.js

@@ -39,6 +39,7 @@ export class SessionState {
     lastMessageAt;
     status = 'ACTIVE';
     pendingMessages = [];
+    seenMessageIds = new Set();
     ackToken = null;
     constructor(taskId, sessionId, projectId, createdAt = new Date()) {
         this.taskId = taskId;
@@ -102,7 +103,10 @@ export class SessionManager {
             if (!session) {
                 return;
             }
+            if (session.seenMessageIds.has(message.messageId))
+                return;
             const record = new MessageRecord(message);
+            session.seenMessageIds.add(record.messageId);
             session.pendingMessages.push(record);
             session.lastMessageAt = record.createdAt;
             this.ensureEvent(taskId).signal();

package/dist/ws/client.js

@@ -1,3 +1,4 @@
+import { buildFireHostName } from '../agent-host.js';
 class AsyncLock {
     tail = Promise.resolve();
     async runExclusive(fn) {
@@ -443,9 +444,7 @@ async function defaultConnectImpl(url, options) {
     });
 }
 function defaultHostName() {
-    const pid = process.pid;
-    const host = process.env.HOSTNAME || process.env.COMPUTERNAME || 'unknown-host';
-    return `conductor-fire-${host}-${pid}`;
+    return buildFireHostName(process.env);
 }
 class WsAdapter {
     ws;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@love-moon/conductor-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovemoon-ai/conductor.git"
@@ -33,5 +33,5 @@
     "typescript": "^5.6.3",
     "vitest": "^2.1.4"
   },
-  "gitCommitId": "04d4f62"
+  "gitCommitId": "bc7b3a5"
 }