@love-moon/conductor-sdk 0.7.7 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @love-moon/conductor-sdk
 
+## 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
+
+- 959dd1d: Add project-configured worker and reviewer task groups, task-group discovery in
+  the SDK and `conductor task group`, and a lightweight daemon protocol for
+  refreshing the project agent registry.
+- fe76139: Add `conductor task create` for creating app tasks with title, prompt, backend,
+  project resolution, and optional parent task-card grouping. App tasks now
+  require an online compatible daemon, and grouping results are exposed to
+  callers so partial success is visible without retrying task creation.
+
 ## 0.7.7
 
 ### Patch 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/api/index.d.ts

@@ -1,4 +1,4 @@
 export { ProjectsApi, type Project, type CreateProjectInput, type ListProjectsOptions, type ResolveProjectInput, } from './projects.js';
 export { IssuesApi, type Issue, type ListIssuesInput, type CreateIssueInput, type UpdateIssueInput, type UpdateIssueStatusOptions, } from './issues.js';
-export { TasksApi, type Task, type Message, type ListTasksInput, type SendTaskMessageOptions, type ListTaskMessagesOptions, type ScheduledMessage, type ScheduledMessageSchedule, type CreateScheduledMessageInput, } from './tasks.js';
+export { TasksApi, type Task, type TaskGroupingResult, type TaskGroup, type TaskGroupMember, type Message, type ListTasksInput, type CreateTaskInput, type SendTaskMessageOptions, type ListTaskMessagesOptions, type ScheduledMessage, type ScheduledMessageSchedule, type CreateScheduledMessageInput, } from './tasks.js';
 export { ProjectNotResolvedError, buildAuditMetadata, isBackendApiError, type ApiClient, type SdkClientOptions, } from './shared.js';

package/dist/api/shared.d.ts

@@ -1,5 +1,5 @@
 import { BackendApiClient, BackendApiError } from '../backend/index.js';
-export type ApiClient = Pick<BackendApiClient, 'listProjects' | 'createProject' | 'getProject' | 'updateProject' | 'patchProjectByQuery' | 'setDefaultProject' | 'matchProjectByPath' | 'listIssues' | 'getIssue' | 'createIssue' | 'patchIssue' | 'deleteIssue' | 'listTasks' | 'getTask' | 'listTaskMessages' | 'postTaskMessage' | 'postTaskInsert' | 'listScheduledMessages' | 'createScheduledMessage' | 'deleteScheduledMessage'>;
+export type ApiClient = Pick<BackendApiClient, 'listProjects' | 'createProject' | 'getProject' | 'updateProject' | 'patchProjectByQuery' | 'setDefaultProject' | 'matchProjectByPath' | 'listIssues' | 'getIssue' | 'createIssue' | 'patchIssue' | 'deleteIssue' | 'listTasks' | 'createTask' | 'createAppTask' | 'getTask' | 'getTaskGroup' | 'listTaskMessages' | 'postTaskMessage' | 'postTaskInsert' | 'listScheduledMessages' | 'createScheduledMessage' | 'deleteScheduledMessage'>;
 export interface SdkClientOptions {
     /**
      * Optional override for the SDK version stamped onto audit metadata. Falls

package/dist/api/tasks.d.ts

@@ -10,8 +10,14 @@ export interface Task {
     sessionFilePath?: string | null;
     createdAt?: string | null;
     updatedAt?: string | null;
+    grouping?: TaskGroupingResult | null;
     raw: Record<string, unknown>;
 }
+export interface TaskGroupingResult {
+    parentTaskId: string;
+    grouped: boolean;
+    warning?: string | null;
+}
 export interface Message {
     id: string;
     taskId?: string | null;
@@ -21,6 +27,21 @@ export interface Message {
     createdAt?: string | null;
     raw: Record<string, unknown>;
 }
+/** RFC 0033 — one member of a multi-agent task group. */
+export interface TaskGroupMember {
+    taskId: string;
+    role: string | null;
+    agent: string | null;
+    title: string | null;
+    status: string | null;
+    backendType: string | null;
+    isSelf: boolean;
+}
+/** RFC 0033 — the group a task belongs to (groupId null when standalone). */
+export interface TaskGroup {
+    groupId: string | null;
+    members: TaskGroupMember[];
+}
 export type ScheduledMessageSchedule = {
     mode: 'delay';
     amount: number;
@@ -71,6 +92,14 @@ export interface ListTasksInput {
     issueId?: string;
     status?: string | string[];
 }
+export interface CreateTaskInput {
+    projectId: string;
+    title: string;
+    backendType?: string;
+    initialContent?: string;
+    parentTaskId?: string;
+    metadata?: Record<string, unknown>;
+}
 export interface SendTaskMessageOptions {
     role?: string;
     metadata?: Record<string, unknown>;
@@ -99,6 +128,14 @@ export declare class TasksApi {
     constructor(client: ApiClient, options?: SdkClientOptions);
     listTasks(input?: ListTasksInput): Promise<Task[]>;
     getTask(taskId: string): Promise<Task>;
+    createTask(input: CreateTaskInput): Promise<Task>;
+    /**
+     * RFC 0033 — resolve the multi-agent group a task belongs to. Returns the
+     * group id (null if the task is standalone) and every sibling task with its
+     * role/agent. Agents use this to discover the task(s) they read from / send
+     * feedback to.
+     */
+    getTaskGroup(taskId: string): Promise<TaskGroup>;
     sendTaskMessage(taskId: string, content: string, options?: SendTaskMessageOptions): Promise<Message>;
     /**
      * Insert a mid-turn message into a running task. The message is delivered and

package/dist/api/tasks.js

@@ -4,6 +4,21 @@ const normalizeTask = (payload) => {
     if (!id) {
         throw new Error('Task payload missing id');
     }
+    const groupingPayload = payload.grouping && typeof payload.grouping === 'object' && !Array.isArray(payload.grouping)
+        ? payload.grouping
+        : null;
+    const groupingParentTaskId = groupingPayload
+        ? groupingPayload.parentTaskId ?? groupingPayload.parent_task_id
+        : null;
+    const grouping = groupingParentTaskId && typeof groupingPayload?.grouped === 'boolean'
+        ? {
+            parentTaskId: String(groupingParentTaskId),
+            grouped: groupingPayload.grouped,
+            warning: typeof groupingPayload.warning === 'string'
+                ? groupingPayload.warning
+                : null,
+        }
+        : null;
     return {
         id,
         projectId: payload.projectId !== undefined
@@ -23,9 +38,27 @@ const normalizeTask = (payload) => {
         sessionFilePath: payload.sessionFilePath ?? payload.session_file_path ?? null,
         createdAt: payload.createdAt ?? payload.created_at ?? null,
         updatedAt: payload.updatedAt ?? payload.updated_at ?? null,
+        grouping,
         raw: payload,
     };
 };
+const asStringOrNull = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
+const normalizeTaskGroup = (payload) => {
+    const rawMembers = Array.isArray(payload?.members) ? payload.members : [];
+    const members = rawMembers.map((m) => ({
+        taskId: String(m?.task_id ?? m?.taskId ?? ''),
+        role: asStringOrNull(m?.role),
+        agent: asStringOrNull(m?.agent),
+        title: asStringOrNull(m?.title),
+        status: asStringOrNull(m?.status),
+        backendType: asStringOrNull(m?.backend_type ?? m?.backendType),
+        isSelf: Boolean(m?.is_self ?? m?.isSelf),
+    }));
+    return {
+        groupId: asStringOrNull(payload?.group_id ?? payload?.groupId),
+        members,
+    };
+};
 const normalizeMessage = (payload) => {
     const id = payload.id ? String(payload.id) : payload.message_id ? String(payload.message_id) : '';
     if (!id) {
@@ -129,6 +162,49 @@ export class TasksApi {
             ? summary.asObject()
             : summary);
     }
+    async createTask(input) {
+        const projectId = String(input?.projectId ?? '').trim();
+        const title = String(input?.title ?? '').trim();
+        if (!projectId) {
+            throw new Error('projectId is required');
+        }
+        if (!title) {
+            throw new Error('title is required');
+        }
+        const params = {
+            projectId,
+            title,
+            taskType: 'ai_task',
+            metadata: buildAuditMetadata(input.metadata, this.options),
+        };
+        if (input.backendType !== undefined) {
+            params.backendType = input.backendType;
+        }
+        if (input.initialContent !== undefined) {
+            params.initialContent = input.initialContent;
+        }
+        if (input.parentTaskId !== undefined) {
+            params.parentTaskId = input.parentTaskId;
+        }
+        const payload = await this.client.createAppTask(params);
+        return normalizeTask(typeof payload.asObject === 'function'
+            ? payload.asObject()
+            : payload);
+    }
+    /**
+     * RFC 0033 — resolve the multi-agent group a task belongs to. Returns the
+     * group id (null if the task is standalone) and every sibling task with its
+     * role/agent. Agents use this to discover the task(s) they read from / send
+     * feedback to.
+     */
+    async getTaskGroup(taskId) {
+        const trimmed = String(taskId ?? '').trim();
+        if (!trimmed) {
+            throw new Error('taskId is required');
+        }
+        const payload = await this.client.getTaskGroup(trimmed);
+        return normalizeTaskGroup(payload);
+    }
     async sendTaskMessage(taskId, content, options = {}) {
         const trimmed = String(taskId ?? '').trim();
         if (!trimmed) {

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.d.ts

@@ -4,6 +4,20 @@ export interface BackendClientOptions {
     fetchImpl?: FetchFn;
     timeoutMs?: number;
 }
+export interface BackendCreateTaskParams {
+    id?: string;
+    projectId: string;
+    title: string;
+    taskType?: string;
+    status?: string;
+    backendType?: string;
+    sessionId?: string | null;
+    sessionFilePath?: string | null;
+    initialContent?: string;
+    agentHost?: string;
+    parentTaskId?: string;
+    metadata?: Record<string, unknown>;
+}
 export type AgentCommitEvent = {
     eventType: 'sdk_message';
     taskId: string;
@@ -48,6 +62,11 @@ export declare class ProjectSummary {
     static fromJSON(payload: Record<string, any>): ProjectSummary;
     asObject(): Record<string, unknown>;
 }
+export interface TaskGroupingSummary {
+    parentTaskId: string;
+    grouped: boolean;
+    warning?: string | null;
+}
 export declare class TaskSummary {
     readonly id: string;
     readonly projectId: string | null;
@@ -58,7 +77,8 @@ export declare class TaskSummary {
     readonly sessionFilePath?: string | null | undefined;
     readonly createdAt?: string | null | undefined;
     readonly updatedAt?: string | null | undefined;
-    constructor(id: string, projectId: string | null, title: string, status: string, backendType?: string | null | undefined, sessionId?: string | null | undefined, sessionFilePath?: string | null | undefined, createdAt?: string | null | undefined, updatedAt?: string | null | undefined);
+    readonly grouping?: (TaskGroupingSummary | null) | undefined;
+    constructor(id: string, projectId: string | null, title: string, status: string, backendType?: string | null | undefined, sessionId?: string | null | undefined, sessionFilePath?: string | null | undefined, createdAt?: string | null | undefined, updatedAt?: string | null | undefined, grouping?: (TaskGroupingSummary | null) | undefined);
     static fromJSON(payload: Record<string, any>): TaskSummary;
 }
 export declare class BackendApiClient {
@@ -85,19 +105,19 @@ export declare class BackendApiClient {
         projectId?: string;
         status?: string;
     }): Promise<TaskSummary[]>;
-    createTask(params: {
-        id?: string;
-        projectId: string;
-        title: string;
-        status?: string;
-        backendType?: string;
-        sessionId?: string | null;
-        sessionFilePath?: string | null;
-        initialContent?: string;
-        agentHost?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<TaskSummary>;
+    createTask(params: BackendCreateTaskParams): Promise<TaskSummary>;
+    /**
+     * Create an app-managed task through the frontend pipeline. This route
+     * assigns daemon ownership and delivers initialContent; it is intentionally
+     * separate from the legacy agent/fire POST /tasks endpoint.
+     */
+    createAppTask(params: BackendCreateTaskParams): Promise<TaskSummary>;
     getTask(taskId: string): Promise<TaskSummary>;
+    /**
+     * GET /tasks/[taskId]/group — RFC 0033 task-group discovery. Returns the raw
+     * payload `{ group_id, members }`; the higher layer normalizes it.
+     */
+    getTaskGroup(taskId: string): Promise<Record<string, any>>;
     updateTask(taskId: string, params: {
         projectId?: string;
         title?: string;

package/dist/backend/client.js

@@ -62,7 +62,8 @@ export class TaskSummary {
     sessionFilePath;
     createdAt;
     updatedAt;
-    constructor(id, projectId, title, status, backendType, sessionId, sessionFilePath, createdAt, updatedAt) {
+    grouping;
+    constructor(id, projectId, title, status, backendType, sessionId, sessionFilePath, createdAt, updatedAt, grouping) {
         this.id = id;
         this.projectId = projectId;
         this.title = title;
@@ -72,6 +73,7 @@ export class TaskSummary {
         this.sessionFilePath = sessionFilePath;
         this.createdAt = createdAt;
         this.updatedAt = updatedAt;
+        this.grouping = grouping;
     }
     static fromJSON(payload) {
         const id = payload.id ? String(payload.id) : '';
@@ -83,7 +85,22 @@ export class TaskSummary {
         if (!title || !status) {
             throw new Error('Task payload missing required fields');
         }
-        return new TaskSummary(id, payload.project_id ? String(payload.project_id) : null, title, status, payload.backend_type ?? payload.backendType ?? null, payload.session_id ?? payload.sessionId ?? null, payload.session_file_path ?? payload.sessionFilePath ?? null, payload.created_at ?? null, payload.updated_at ?? null);
+        const groupingPayload = payload.grouping && typeof payload.grouping === 'object' && !Array.isArray(payload.grouping)
+            ? payload.grouping
+            : null;
+        const groupingParentTaskId = groupingPayload
+            ? groupingPayload.parent_task_id ?? groupingPayload.parentTaskId
+            : null;
+        const grouping = groupingParentTaskId && typeof groupingPayload?.grouped === 'boolean'
+            ? {
+                parentTaskId: String(groupingParentTaskId),
+                grouped: groupingPayload.grouped,
+                warning: typeof groupingPayload.warning === 'string'
+                    ? groupingPayload.warning
+                    : null,
+            }
+            : null;
+        return new TaskSummary(id, payload.project_id ? String(payload.project_id) : null, title, status, payload.backend_type ?? payload.backendType ?? null, payload.session_id ?? payload.sessionId ?? null, payload.session_file_path ?? payload.sessionFilePath ?? null, payload.created_at ?? null, payload.updated_at ?? null, grouping);
     }
 }
 export class BackendApiClient {
@@ -160,11 +177,35 @@ export class BackendApiClient {
         const payload = await this.parseJson(response);
         return TaskSummary.fromJSON(payload);
     }
+    /**
+     * Create an app-managed task through the frontend pipeline. This route
+     * assigns daemon ownership and delivers initialContent; it is intentionally
+     * separate from the legacy agent/fire POST /tasks endpoint.
+     */
+    async createAppTask(params) {
+        const response = await this.request('POST', '/api/tasks', {
+            body: JSON.stringify(params),
+        });
+        const payload = await this.parseJson(response);
+        return TaskSummary.fromJSON(payload);
+    }
     async getTask(taskId) {
         const response = await this.request('GET', `/tasks/${taskId}`);
         const payload = await this.parseJson(response);
         return TaskSummary.fromJSON(payload);
     }
+    /**
+     * GET /tasks/[taskId]/group — RFC 0033 task-group discovery. Returns the raw
+     * payload `{ group_id, members }`; the higher layer normalizes it.
+     */
+    async getTaskGroup(taskId) {
+        const response = await this.request('GET', `/tasks/${taskId}/group`);
+        const payload = await this.parseJson(response);
+        if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+            return payload;
+        }
+        throw new BackendApiError('Invalid task group response', response.status, payload);
+    }
     async updateTask(taskId, params) {
         const response = await this.request('PATCH', `/tasks/${taskId}`, {
             body: JSON.stringify(params),

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.7.7",
+  "version": "0.9.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": "26b2dbb"
+  "gitCommitId": "606e5a6"
 }