@parall/agent-core 1.13.1

package/dist/gateway-base.js

@@ -0,0 +1,865 @@
+import * as os from "node:os";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { MENTION_ALL_USER_ID } from "@parall/sdk";
+import { buildEventBody, buildForkResultPrefix } from "./event-format.js";
+import { routeTrigger } from "./routing.js";
+import { clearDispatchMessageId, clearDispatchNoReply, clearSessionMessageId, setDispatchMessageId, setDispatchNoReply, setSessionChatId, setSessionMessageId, } from "./session-state.js";
+function resolveStepTarget(event) {
+    if (event.type === "task" || event.targetId.startsWith("tsk_")) {
+        return { target_type: "task", target_id: event.targetId };
+    }
+    if (event.targetId.startsWith("cht_")) {
+        return { target_type: "chat", target_id: event.targetId };
+    }
+    return { target_type: "", target_id: event.targetId || undefined };
+}
+async function fetchAllChats(client, orgId, chatInfoMap) {
+    let cursor;
+    let total = 0;
+    do {
+        const res = await client.getChats(orgId, { limit: 100, cursor });
+        for (const chat of res.data) {
+            chatInfoMap.set(chat.id, {
+                type: chat.type,
+                name: chat.name ?? null,
+                agentRoutingMode: chat.agent_routing_mode,
+            });
+        }
+        total += res.data.length;
+        cursor = res.has_more ? res.next_cursor : undefined;
+    } while (cursor);
+    return total;
+}
+export class ParallAgentGateway {
+    opts;
+    chatInfoMap = new Map();
+    activeDispatches = new Map();
+    dispatchedTasks = new Set();
+    dispatchedMessages = new Set();
+    forkStates = new Map();
+    dispatchState = {
+        mainDispatching: false,
+        activeForks: new Map(),
+        pendingForkResults: [],
+        mainBuffer: [],
+    };
+    sessionId = "";
+    activeSessionId;
+    heartbeatTimer = null;
+    hadSuccessfulHello = false;
+    lastHeartbeatAt = Date.now();
+    draining = false;
+    DISPATCHED_MESSAGES_CAP = 5000;
+    COLD_START_WINDOW_MS;
+    constructor(opts) {
+        this.opts = opts;
+        this.COLD_START_WINDOW_MS = opts.coldStartWindowMs ?? 5 * 60_000;
+    }
+    async run(abortSignal) {
+        const { ws, log } = this.opts;
+        ws.onStateChange((state) => {
+            log?.info(`parall[${this.opts.accountId}]: connection state → ${state}`);
+        });
+        ws.on("hello", async (data) => {
+            await this.handleHello(data);
+        });
+        ws.on("chat.update", (data) => {
+            const changes = data.changes;
+            if (!changes)
+                return;
+            const existing = this.chatInfoMap.get(data.chat_id);
+            if (existing) {
+                this.chatInfoMap.set(data.chat_id, {
+                    ...existing,
+                    ...(typeof changes.type === "string" ? { type: changes.type } : {}),
+                    ...(typeof changes.name === "string" ? { name: changes.name } : {}),
+                    ...(typeof changes.agent_routing_mode === "string"
+                        ? { agentRoutingMode: changes.agent_routing_mode }
+                        : {}),
+                });
+            }
+            else if (typeof changes.type === "string") {
+                this.chatInfoMap.set(data.chat_id, {
+                    type: changes.type,
+                    name: typeof changes.name === "string" ? changes.name : null,
+                    agentRoutingMode: (typeof changes.agent_routing_mode === "string"
+                        ? changes.agent_routing_mode
+                        : "passive"),
+                });
+            }
+        });
+        ws.on("message.new", async (data) => {
+            await this.handleMessage(data);
+        });
+        ws.on("agent_config.update", async (data) => {
+            this.opts.log?.info(`parall[${this.opts.accountId}]: config update notification (version=${data.version})`);
+            try {
+                await this.opts.onConfigUpdate?.(data);
+            }
+            catch (err) {
+                this.opts.log?.warn(`parall[${this.opts.accountId}]: config update failed: ${String(err)}`);
+            }
+        });
+        ws.on("recovery.overflow", () => {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: recovery.overflow — triggering full catch-up`);
+            this.catchUpFromDispatch().catch((err) => this.opts.log?.warn(`parall[${this.opts.accountId}]: overflow catch-up failed: ${String(err)}`));
+        });
+        ws.on("task.assigned", async (data) => {
+            if (data.assignee_id !== this.opts.agentUserId)
+                return;
+            if (data.status !== "todo" && data.status !== "in_progress")
+                return;
+            try {
+                const dispatched = await this.handleTaskAssignment(data, data.id);
+                if (dispatched) {
+                    this.opts.client.ackDispatch(this.opts.config.org_id, { source_type: "task_activity", source_id: data.id }).catch(() => { });
+                }
+            }
+            catch (err) {
+                this.opts.log?.error(`parall[${this.opts.accountId}]: task dispatch failed for ${data.id}: ${String(err)}`);
+            }
+        });
+        this.opts.log?.info(`parall[${this.opts.accountId}]: connecting to ${this.opts.connectionLabel ?? "Parall WS"}...`);
+        await ws.connect();
+        return new Promise((resolve) => {
+            abortSignal.addEventListener("abort", async () => {
+                await this.shutdown();
+                resolve();
+            });
+        });
+    }
+    tryClaimMessage(id) {
+        if (this.dispatchedMessages.has(id))
+            return false;
+        if (this.dispatchedMessages.size >= this.DISPATCHED_MESSAGES_CAP) {
+            let toEvict = Math.floor(this.DISPATCHED_MESSAGES_CAP / 4);
+            for (const old of this.dispatchedMessages) {
+                this.dispatchedMessages.delete(old);
+                if (--toEvict <= 0)
+                    break;
+            }
+        }
+        this.dispatchedMessages.add(id);
+        return true;
+    }
+    startTyping(chatId) {
+        const existing = this.activeDispatches.get(chatId);
+        if (existing) {
+            existing.count++;
+            return;
+        }
+        if (this.opts.ws.state === "connected")
+            this.opts.ws.sendTyping(chatId, "start");
+        const typingRefresh = setInterval(() => {
+            if (this.opts.ws.state === "connected")
+                this.opts.ws.sendTyping(chatId, "start");
+        }, 2000);
+        this.activeDispatches.set(chatId, { count: 1, typingTimer: typingRefresh });
+    }
+    stopTyping(chatId) {
+        const dispatch = this.activeDispatches.get(chatId);
+        if (!dispatch)
+            return;
+        dispatch.count--;
+        if (dispatch.count > 0)
+            return;
+        clearInterval(dispatch.typingTimer);
+        this.activeDispatches.delete(chatId);
+        if (this.opts.ws.state === "connected")
+            this.opts.ws.sendTyping(chatId, "stop");
+    }
+    buildDispatchContext(event, sessionKey) {
+        return {
+            accountId: this.opts.accountId,
+            apiUrl: this.opts.config.parall_url,
+            apiKey: this.opts.config.api_key,
+            orgId: this.opts.config.org_id,
+            agentUserId: this.opts.agentUserId,
+            runtimeType: this.opts.runtimeType,
+            runtimeKey: this.opts.runtimeKey,
+            sessionId: this.activeSessionId,
+            chatId: event.type === "message" ? event.targetId : undefined,
+            triggerMessageId: event.messageId,
+            noReply: event.noReply ?? false,
+            stepIdFilePath: this.opts.stepIdFilePathForSession?.(sessionKey),
+            client: this.opts.client,
+            log: this.opts.log,
+        };
+    }
+    async createInputStep(event) {
+        if (!this.activeSessionId)
+            return;
+        const target = resolveStepTarget(event);
+        try {
+            await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                step_type: "input",
+                target_type: target.target_type,
+                target_id: target.target_id,
+                content: {
+                    trigger_type: event.type === "task" ? "task_assign" : "mention",
+                    trigger_ref: event.type === "task" ? { task_id: event.targetId } : { message_id: event.messageId },
+                    sender_id: event.senderId,
+                    sender_name: event.senderName,
+                    summary: event.body.substring(0, 200),
+                },
+            });
+        }
+        catch (err) {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to create input step: ${String(err)}`);
+        }
+    }
+    async createRuntimeStep(event, runtimeEvent, stepIdFilePath) {
+        if (!this.activeSessionId)
+            return;
+        const target = resolveStepTarget(event);
+        try {
+            switch (runtimeEvent.type) {
+                case "thinking":
+                    await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                        step_type: "thinking",
+                        target_type: target.target_type,
+                        target_id: target.target_id,
+                        content: { text: runtimeEvent.text },
+                        group_key: runtimeEvent.groupKey,
+                    });
+                    break;
+                case "text":
+                    await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                        step_type: "text",
+                        target_type: target.target_type,
+                        target_id: target.target_id,
+                        content: {
+                            text: runtimeEvent.text,
+                            suppressed: runtimeEvent.project !== true,
+                        },
+                        projection: runtimeEvent.project === true,
+                        group_key: runtimeEvent.groupKey,
+                    });
+                    break;
+                case "tool_call": {
+                    const step = await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                        step_type: "tool_call",
+                        target_type: target.target_type,
+                        target_id: target.target_id,
+                        content: {
+                            call_id: runtimeEvent.callId,
+                            tool_name: runtimeEvent.toolName,
+                            tool_input: runtimeEvent.input,
+                            status: "running",
+                            started_at: runtimeEvent.startedAt ?? new Date().toISOString(),
+                        },
+                        group_key: runtimeEvent.groupKey,
+                        runtime_key: runtimeEvent.callId,
+                    });
+                    if (stepIdFilePath) {
+                        this.writeStepIdFile(stepIdFilePath, step.id);
+                    }
+                    break;
+                }
+                case "tool_result":
+                    await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                        step_type: "tool_result",
+                        target_type: target.target_type,
+                        target_id: target.target_id,
+                        content: {
+                            call_id: runtimeEvent.callId,
+                            tool_name: runtimeEvent.toolName,
+                            status: runtimeEvent.error ? "error" : "success",
+                            output: runtimeEvent.output,
+                            duration_ms: runtimeEvent.durationMs ?? 0,
+                            collapsible: true,
+                        },
+                        group_key: runtimeEvent.groupKey,
+                    });
+                    if (stepIdFilePath) {
+                        this.clearStepIdFile(stepIdFilePath);
+                    }
+                    break;
+                case "error":
+                    await this.opts.client.createAgentStep(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                        step_type: "text",
+                        target_type: target.target_type,
+                        target_id: target.target_id,
+                        content: { text: runtimeEvent.message, suppressed: false },
+                        projection: true,
+                    });
+                    break;
+            }
+        }
+        catch (err) {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to create ${runtimeEvent.type} step: ${String(err)}`);
+        }
+    }
+    writeStepIdFile(filePath, stepId) {
+        try {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, stepId, "utf8");
+        }
+        catch (err) {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to write step id file ${filePath}: ${String(err)}`);
+        }
+    }
+    clearStepIdFile(filePath) {
+        try {
+            fs.writeFileSync(filePath, "", "utf8");
+        }
+        catch {
+            // Best-effort cleanup.
+        }
+    }
+    async createInputStepsForEarlierEvents(events) {
+        for (const event of events) {
+            await this.createInputStep(event);
+        }
+    }
+    async runDispatch(event, sessionKey, bodyForAgent, earlierEvents = []) {
+        setSessionChatId(sessionKey, event.targetId);
+        setSessionMessageId(sessionKey, event.messageId);
+        setDispatchMessageId(sessionKey, event.messageId);
+        setDispatchNoReply(sessionKey, event.noReply ?? false);
+        const dispatchContext = this.buildDispatchContext(event, sessionKey);
+        const stepIdFilePath = dispatchContext.stepIdFilePath;
+        try {
+            if (this.activeSessionId) {
+                try {
+                    await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active" });
+                }
+                catch (err) {
+                    this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to set session active: ${String(err)}`);
+                }
+            }
+            await this.createInputStep(event);
+            for await (const runtimeEvent of this.opts.dispatchAdapter.dispatch({
+                event,
+                earlierEvents,
+                bodyForAgent,
+                sessionKey,
+                context: dispatchContext,
+            })) {
+                await this.createRuntimeStep(event, runtimeEvent, stepIdFilePath);
+            }
+        }
+        catch (err) {
+            await this.createRuntimeStep(event, {
+                type: "error",
+                message: `Dispatch failed: ${String(err)}`,
+            }, stepIdFilePath);
+            throw err;
+        }
+        finally {
+            clearSessionMessageId(sessionKey);
+            clearDispatchMessageId(sessionKey);
+            clearDispatchNoReply(sessionKey);
+            if (stepIdFilePath) {
+                this.clearStepIdFile(stepIdFilePath);
+            }
+            if (this.activeSessionId) {
+                try {
+                    await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "idle" });
+                }
+                catch (err) {
+                    this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to set session idle: ${String(err)}`);
+                }
+            }
+        }
+    }
+    async runForkDrainLoop(fork) {
+        try {
+            while (fork.queue.length > 0) {
+                const items = fork.queue.splice(0);
+                const events = items.map((item) => item.event);
+                const last = events[events.length - 1];
+                const earlier = events.slice(0, -1);
+                try {
+                    if (earlier.length > 0) {
+                        await this.createInputStepsForEarlierEvents(earlier);
+                    }
+                    await this.runDispatch(last, fork.fork.sessionKey, buildEventBody(last), earlier);
+                    fork.processedEvents.push(...events);
+                    for (const item of items) {
+                        item.resolve(true);
+                    }
+                }
+                catch (err) {
+                    this.opts.log?.error(`parall[${this.opts.accountId}]: fork dispatch failed for ${last.messageId}: ${String(err)}`);
+                    for (const item of items) {
+                        item.resolve(false);
+                    }
+                    break;
+                }
+            }
+            for (const remaining of fork.queue.splice(0)) {
+                remaining.resolve(false);
+            }
+        }
+        finally {
+            if (fork.processedEvents.length > 0) {
+                const first = fork.processedEvents[0];
+                this.dispatchState.pendingForkResults.push({
+                    forkSessionKey: fork.fork.sessionKey,
+                    sourceEvent: {
+                        type: first.type,
+                        targetId: fork.targetId,
+                        summary: fork.processedEvents.length === 1
+                            ? `${first.type} from ${first.senderName} in ${first.targetName ?? fork.targetId}`
+                            : `${fork.processedEvents.length} events in ${first.targetName ?? fork.targetId}`,
+                    },
+                    actions: [],
+                });
+            }
+            this.forkStates.delete(fork.targetId);
+            this.dispatchState.activeForks.delete(fork.targetId);
+            if (this.opts.dispatchAdapter.cleanupFork) {
+                const cleanupOpts = {
+                    fork: fork.fork,
+                    context: {
+                        accountId: this.opts.accountId,
+                        apiUrl: this.opts.config.parall_url,
+                        apiKey: this.opts.config.api_key,
+                        orgId: this.opts.config.org_id,
+                        agentUserId: this.opts.agentUserId,
+                        runtimeType: this.opts.runtimeType,
+                        runtimeKey: this.opts.runtimeKey,
+                        sessionId: this.activeSessionId,
+                        noReply: false,
+                        client: this.opts.client,
+                        log: this.opts.log,
+                    },
+                };
+                await this.opts.dispatchAdapter.cleanupFork(cleanupOpts);
+            }
+        }
+    }
+    async drainMainBuffer() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            while (this.dispatchState.mainBuffer.length > 0 || this.dispatchState.pendingForkResults.length > 0) {
+                if (this.dispatchState.mainBuffer.length === 0 && this.dispatchState.pendingForkResults.length > 0) {
+                    const forkPrefix = buildForkResultPrefix(this.dispatchState.pendingForkResults.splice(0));
+                    const syntheticEvent = {
+                        type: "message",
+                        targetId: "_orchestrator",
+                        targetType: "system",
+                        senderId: "system",
+                        senderName: "system",
+                        messageId: `synthetic-${this.opts.accountId}-${randomUUID()}`,
+                        body: "[Orchestrator: fork session(s) completed — review results above]",
+                    };
+                    this.dispatchState.mainCurrentTargetId = undefined;
+                    await this.runDispatch(syntheticEvent, this.opts.runtimeKey, forkPrefix + buildEventBody(syntheticEvent));
+                    continue;
+                }
+                const targetId = this.dispatchState.mainBuffer[0].targetId;
+                const events = [];
+                while (this.dispatchState.mainBuffer[0]?.targetId === targetId) {
+                    events.push(this.dispatchState.mainBuffer.shift());
+                }
+                const event = events[events.length - 1];
+                const earlier = events.slice(0, -1);
+                const forkPrefix = buildForkResultPrefix(this.dispatchState.pendingForkResults.splice(0));
+                this.dispatchState.mainCurrentTargetId = event.targetId;
+                if (earlier.length > 0) {
+                    await this.createInputStepsForEarlierEvents(earlier);
+                }
+                await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event), earlier);
+                for (const bufferedEvent of events) {
+                    const sourceType = bufferedEvent.ackSourceType ?? (bufferedEvent.type === "task" ? "task_activity" : "message");
+                    const sourceId = bufferedEvent.ackSourceId ?? bufferedEvent.messageId;
+                    this.opts.client.ackDispatch(this.opts.config.org_id, {
+                        source_type: sourceType,
+                        source_id: sourceId,
+                    }).catch(() => { });
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+            this.dispatchState.mainDispatching = false;
+            this.dispatchState.mainCurrentTargetId = undefined;
+        }
+    }
+    async handleInboundEvent(event) {
+        const disposition = routeTrigger(event, this.dispatchState);
+        switch (disposition.action) {
+            case "main": {
+                const forkPrefix = buildForkResultPrefix(this.dispatchState.pendingForkResults.splice(0));
+                this.dispatchState.mainDispatching = true;
+                this.dispatchState.mainCurrentTargetId = event.targetId;
+                try {
+                    await this.runDispatch(event, this.opts.runtimeKey, forkPrefix + buildEventBody(event));
+                }
+                finally {
+                    await this.drainMainBuffer();
+                }
+                return true;
+            }
+            case "buffer-main":
+                this.dispatchState.mainBuffer.push(event);
+                return false;
+            case "buffer-fork": {
+                const activeFork = this.forkStates.get(event.targetId);
+                if (!activeFork) {
+                    this.dispatchState.mainBuffer.push(event);
+                    return false;
+                }
+                return new Promise((resolve) => {
+                    activeFork.queue.push({ event, resolve });
+                });
+            }
+            case "new-fork": {
+                if (!this.opts.dispatchAdapter.forkSession) {
+                    this.dispatchState.mainBuffer.push(event);
+                    return false;
+                }
+                const fork = await this.opts.dispatchAdapter.forkSession({
+                    sessionKey: this.opts.runtimeKey,
+                    context: this.buildDispatchContext(event, this.opts.runtimeKey),
+                });
+                if (!fork) {
+                    this.opts.log?.warn(`parall[${this.opts.accountId}]: fork failed, buffering event for main session`);
+                    this.dispatchState.mainBuffer.push(event);
+                    return false;
+                }
+                const activeFork = {
+                    fork,
+                    targetId: event.targetId,
+                    queue: [],
+                    processedEvents: [],
+                };
+                this.forkStates.set(event.targetId, activeFork);
+                this.dispatchState.activeForks.set(event.targetId, fork.sessionKey);
+                const firstEventPromise = new Promise((resolve) => {
+                    activeFork.queue.push({ event, resolve });
+                });
+                this.runForkDrainLoop(activeFork).catch((err) => {
+                    this.opts.log?.error(`parall[${this.opts.accountId}]: fork drain loop error: ${String(err)}`);
+                });
+                return firstEventPromise;
+            }
+        }
+    }
+    async getOrFetchChatInfo(chatId) {
+        const cached = this.chatInfoMap.get(chatId);
+        if (cached)
+            return cached;
+        try {
+            const chat = await this.opts.client.getChat(this.opts.config.org_id, chatId);
+            const chatInfo = {
+                type: chat.type,
+                name: chat.name ?? null,
+                agentRoutingMode: chat.agent_routing_mode,
+            };
+            this.chatInfoMap.set(chatId, chatInfo);
+            return chatInfo;
+        }
+        catch (err) {
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to resolve chat ${chatId}: ${String(err)}`);
+            return null;
+        }
+    }
+    async buildMessageDispatchDecision(chatId, message) {
+        if (message.message_type !== "text" && message.message_type !== "file") {
+            return { action: "skip" };
+        }
+        const chatInfo = await this.getOrFetchChatInfo(chatId);
+        if (!chatInfo)
+            return { action: "retry" };
+        let body = "";
+        let mediaFields = {};
+        if (message.message_type === "text") {
+            const content = message.content;
+            body = content.text?.trim() ?? "";
+            if (!body)
+                return { action: "skip" };
+            if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+                const mentions = content.mentions ?? [];
+                const isMentioned = mentions.some((mention) => mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID);
+                if (!isMentioned)
+                    return { action: "skip" };
+            }
+        }
+        else {
+            const content = message.content;
+            if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+                return { action: "skip" };
+            }
+            body = content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`;
+            if (content.attachment_id) {
+                try {
+                    const fileRes = await this.opts.client.getFileUrl(content.attachment_id);
+                    mediaFields = { MediaUrl: fileRes.url, MediaType: content.mime_type };
+                }
+                catch (err) {
+                    this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to get file URL for ${content.attachment_id}: ${String(err)}`);
+                }
+            }
+        }
+        return {
+            action: "dispatch",
+            event: {
+                type: "message",
+                targetId: chatId,
+                targetName: chatInfo.name ?? undefined,
+                targetType: chatInfo.type,
+                senderId: message.sender_id,
+                senderName: message.sender?.display_name ?? message.sender_id,
+                messageId: message.id,
+                body,
+                threadRootId: message.thread_root_id ?? undefined,
+                noReply: message.hints?.no_reply ?? false,
+                mediaFields: Object.keys(mediaFields).length > 0 ? mediaFields : undefined,
+                ackSourceType: "message",
+                ackSourceId: message.id,
+            },
+        };
+    }
+    async handleMessage(data) {
+        const chatId = data.chat_id;
+        if (data.sender_id === this.opts.agentUserId)
+            return;
+        if (data.message_type !== "text" && data.message_type !== "file")
+            return;
+        if (!this.tryClaimMessage(data.id))
+            return;
+        const decision = await this.buildMessageDispatchDecision(chatId, data);
+        if (decision.action !== "dispatch") {
+            this.dispatchedMessages.delete(data.id);
+            return;
+        }
+        const event = decision.event;
+        const willDispatch = !this.dispatchState.mainDispatching || this.dispatchState.mainCurrentTargetId !== chatId;
+        if (willDispatch)
+            this.startTyping(chatId);
+        try {
+            const dispatched = await this.handleInboundEvent(event);
+            if (dispatched) {
+                this.opts.client.ackDispatch(this.opts.config.org_id, { source_type: "message", source_id: data.id }).catch(() => { });
+            }
+            else {
+                this.dispatchedMessages.delete(data.id);
+            }
+        }
+        catch (err) {
+            this.opts.log?.error(`parall[${this.opts.accountId}]: event dispatch failed for ${data.id}: ${String(err)}`);
+            this.dispatchedMessages.delete(data.id);
+        }
+        finally {
+            if (willDispatch)
+                this.stopTyping(chatId);
+        }
+    }
+    async handleTaskAssignment(task, ackSourceId) {
+        const dedupeKey = `${task.id}:${task.updated_at}`;
+        if (this.dispatchedTasks.has(dedupeKey)) {
+            this.opts.log?.info(`parall[${this.opts.accountId}]: skipping already-dispatched task ${task.identifier ?? task.id}`);
+            return false;
+        }
+        this.dispatchedTasks.add(dedupeKey);
+        this.opts.log?.info(`parall[${this.opts.accountId}]: task assigned: ${task.identifier ?? task.id} "${task.title}"`);
+        const parts = [`Title: ${task.title}`];
+        parts.push(`Status: ${task.status}`, `Priority: ${task.priority}`);
+        if (task.description)
+            parts.push("", task.description);
+        const event = {
+            type: "task",
+            targetId: task.id,
+            targetName: task.identifier ?? undefined,
+            targetType: "task",
+            senderId: task.creator_id,
+            senderName: "system",
+            messageId: task.id,
+            body: parts.join("\n"),
+            ackSourceType: "task_activity",
+            ackSourceId,
+        };
+        const dispatched = await this.handleInboundEvent(event);
+        if (!dispatched) {
+            this.dispatchedTasks.delete(dedupeKey);
+        }
+        return dispatched;
+    }
+    async catchUpFromDispatch(coldStart = false) {
+        const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
+        let cursor;
+        let processed = 0;
+        let skippedOld = 0;
+        do {
+            const page = await this.opts.client.getDispatch(this.opts.config.org_id, {
+                limit: 50,
+                cursor,
+            });
+            for (const item of page.data ?? []) {
+                if (minAge > 0 && new Date(item.created_at).getTime() < minAge) {
+                    this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => { });
+                    skippedOld++;
+                    continue;
+                }
+                processed++;
+                try {
+                    let dispatched = false;
+                    if (item.event_type === "task_assign" && item.task_id) {
+                        let task = null;
+                        let taskFetchFailed = false;
+                        try {
+                            task = await this.opts.client.getTask(this.opts.config.org_id, item.task_id);
+                        }
+                        catch (err) {
+                            const status = err?.status;
+                            if (status === 404) {
+                                task = null;
+                            }
+                            else {
+                                taskFetchFailed = true;
+                                this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+                            }
+                        }
+                        if (taskFetchFailed)
+                            continue;
+                        if (task) {
+                            if (task.assignee_id !== this.opts.agentUserId) {
+                                this.opts.log?.info(`parall[${this.opts.accountId}]: skipping stale task dispatch ${item.id} — reassigned to ${task.assignee_id}`);
+                                this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => { });
+                                continue;
+                            }
+                            dispatched = await this.handleTaskAssignment(task);
+                        }
+                        else {
+                            dispatched = true;
+                        }
+                    }
+                    else if (item.event_type === "message" && item.source_id && item.chat_id) {
+                        if (!this.tryClaimMessage(item.source_id))
+                            continue;
+                        let msg = null;
+                        let msgFetchFailed = false;
+                        try {
+                            msg = await this.opts.client.getMessage(item.source_id);
+                        }
+                        catch (err) {
+                            const status = err?.status;
+                            if (status === 404) {
+                                msg = null;
+                            }
+                            else {
+                                msgFetchFailed = true;
+                                this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`);
+                            }
+                        }
+                        if (msgFetchFailed) {
+                            this.dispatchedMessages.delete(item.source_id);
+                            continue;
+                        }
+                        if (!msg || msg.sender_id === this.opts.agentUserId) {
+                            this.dispatchedMessages.delete(item.source_id);
+                            this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => { });
+                            continue;
+                        }
+                        const decision = await this.buildMessageDispatchDecision(item.chat_id, msg);
+                        if (decision.action === "retry") {
+                            this.dispatchedMessages.delete(item.source_id);
+                            continue;
+                        }
+                        if (decision.action === "skip") {
+                            this.dispatchedMessages.delete(item.source_id);
+                            this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => { });
+                            continue;
+                        }
+                        dispatched = await this.handleInboundEvent(decision.event);
+                    }
+                    if (dispatched) {
+                        this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => { });
+                    }
+                }
+                catch (err) {
+                    this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up dispatch ${item.id} (${item.event_type}) failed: ${String(err)}`);
+                }
+            }
+            cursor = page.has_more ? page.next_cursor : undefined;
+        } while (cursor);
+        if (processed > 0 || skippedOld > 0) {
+            this.opts.log?.info(`parall[${this.opts.accountId}]: dispatch catch-up: processed ${processed}, skipped ${skippedOld} old item(s)`);
+        }
+    }
+    async handleHello(data) {
+        const { client, config, log } = this.opts;
+        this.sessionId = data.session_id ?? "";
+        const intervalSec = data.heartbeat_interval > 0 ? data.heartbeat_interval : 30;
+        try {
+            const count = await fetchAllChats(client, config.org_id, this.chatInfoMap);
+            log?.info(`parall[${this.opts.accountId}]: WebSocket connected, ${count} chats cached`);
+            if (!this.activeSessionId) {
+                try {
+                    const session = await client.createAgentSession(config.org_id, this.opts.agentUserId, {
+                        runtime_type: this.opts.runtimeType,
+                        runtime_key: this.opts.runtimeKey,
+                        runtime_ref: this.opts.runtimeRef,
+                    });
+                    this.activeSessionId = session.id;
+                    log?.info(`parall[${this.opts.accountId}]: created agent session ${session.id}`);
+                }
+                catch (err) {
+                    log?.warn(`parall[${this.opts.accountId}]: failed to create agent session: ${String(err)}`);
+                }
+            }
+            await this.opts.onSessionReady?.({
+                activeSessionId: this.activeSessionId,
+                ws: this.opts.ws,
+                runtimeKey: this.opts.runtimeKey,
+            });
+            if (this.heartbeatTimer)
+                clearInterval(this.heartbeatTimer);
+            this.lastHeartbeatAt = Date.now();
+            this.heartbeatTimer = setInterval(() => {
+                const now = Date.now();
+                const expectedMs = intervalSec * 1000;
+                const drift = now - this.lastHeartbeatAt - expectedMs;
+                if (drift > 15000) {
+                    log?.warn(`parall[${this.opts.accountId}]: heartbeat drift ${drift}ms — event loop may be blocked`);
+                }
+                this.lastHeartbeatAt = now;
+                if (this.opts.ws.state !== "connected")
+                    return;
+                this.opts.ws.sendAgentHeartbeat(this.sessionId, {
+                    hostname: os.hostname(),
+                    cores: os.cpus().length,
+                    mem_total: os.totalmem(),
+                    mem_free: os.freemem(),
+                    uptime: os.uptime(),
+                });
+            }, intervalSec * 1000);
+            const isFirstHello = !this.hadSuccessfulHello;
+            this.hadSuccessfulHello = true;
+            this.catchUpFromDispatch(isFirstHello).catch((err) => {
+                log?.warn(`parall[${this.opts.accountId}]: dispatch catch-up failed: ${String(err)}`);
+            });
+        }
+        catch (err) {
+            log?.error(`parall[${this.opts.accountId}]: failed to fetch chats: ${String(err)}`);
+        }
+    }
+    async shutdown() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        for (const [, dispatch] of this.activeDispatches) {
+            clearInterval(dispatch.typingTimer);
+        }
+        this.activeDispatches.clear();
+        await this.opts.onBeforeDisconnect?.();
+        if (this.activeSessionId) {
+            try {
+                await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, {
+                    status: "completed",
+                });
+            }
+            catch (err) {
+                this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to complete session: ${String(err)}`);
+            }
+        }
+        this.opts.ws.disconnect();
+        this.opts.log?.info(`parall[${this.opts.accountId}]: disconnected`);
+    }
+}