@parall/agent-core 1.13.1

package/src/gateway-base.ts

@@ -0,0 +1,989 @@
+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, ParallClient, ParallWs } from "@parall/sdk";
+import type {
+  AgentConfigUpdateData,
+  Chat,
+  ChatUpdateData,
+  HelloData,
+  MediaContent,
+  MessageNewData,
+  Task,
+  TaskAssignedData,
+  TextContent,
+} from "@parall/sdk";
+import { buildEventBody, buildForkResultPrefix } from "./event-format.js";
+import type {
+  CleanupForkOpts,
+  DispatchAdapter,
+  DispatchContext,
+  ForkSessionHandle,
+  GatewayLogger,
+  RuntimeEvent,
+} from "./dispatch-adapter.js";
+import { routeTrigger } from "./routing.js";
+import {
+  clearDispatchMessageId,
+  clearDispatchNoReply,
+  clearSessionMessageId,
+  setDispatchMessageId,
+  setDispatchNoReply,
+  setSessionChatId,
+  setSessionMessageId,
+} from "./session-state.js";
+import type { DispatchState, ParallEvent } from "./types.js";
+
+type ChatInfo = {
+  type: Chat["type"];
+  name: string | null;
+  agentRoutingMode: Chat["agent_routing_mode"];
+};
+
+type ActiveDispatch = {
+  count: number;
+  typingTimer: ReturnType<typeof setInterval>;
+};
+
+type ForkQueueItem = {
+  event: ParallEvent;
+  resolve: (dispatched: boolean) => void;
+};
+
+type ActiveForkState = {
+  fork: ForkSessionHandle;
+  targetId: string;
+  queue: ForkQueueItem[];
+  processedEvents: ParallEvent[];
+};
+
+type DispatchableMessage = {
+  id: string;
+  sender_id: string;
+  sender?: { display_name?: string | null };
+  message_type: string;
+  content: unknown;
+  thread_root_id?: string | null;
+  hints?: { no_reply?: boolean } | null;
+};
+
+type MessageDispatchDecision =
+  | { action: "dispatch"; event: ParallEvent }
+  | { action: "skip" }
+  | { action: "retry" };
+
+export type ParallGatewayOptions = {
+  accountId: string;
+  client: ParallClient;
+  ws: ParallWs;
+  connectionLabel?: string;
+  config: {
+    parall_url: string;
+    api_key: string;
+    org_id: string;
+  };
+  agentUserId: string;
+  runtimeType: string;
+  runtimeKey: string;
+  runtimeRef?: Record<string, unknown>;
+  dispatchAdapter: DispatchAdapter;
+  log?: GatewayLogger;
+  coldStartWindowMs?: number;
+  stepIdFilePathForSession?: (sessionKey: string) => string | undefined;
+  onConfigUpdate?: (data: AgentConfigUpdateData) => Promise<void> | void;
+  onSessionReady?: (state: { activeSessionId?: string; ws: ParallWs; runtimeKey: string }) => Promise<void> | void;
+  onBeforeDisconnect?: () => Promise<void> | void;
+};
+
+function resolveStepTarget(event: ParallEvent): { target_type: string; target_id?: string } {
+  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: ParallClient,
+  orgId: string,
+  chatInfoMap: Map<string, ChatInfo>,
+): Promise<number> {
+  let cursor: string | undefined;
+  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 {
+  private readonly chatInfoMap = new Map<string, ChatInfo>();
+  private readonly activeDispatches = new Map<string, ActiveDispatch>();
+  private readonly dispatchedTasks = new Set<string>();
+  private readonly dispatchedMessages = new Set<string>();
+  private readonly forkStates = new Map<string, ActiveForkState>();
+  private readonly dispatchState: DispatchState = {
+    mainDispatching: false,
+    activeForks: new Map(),
+    pendingForkResults: [],
+    mainBuffer: [],
+  };
+
+  private sessionId = "";
+  private activeSessionId: string | undefined;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private hadSuccessfulHello = false;
+  private lastHeartbeatAt = Date.now();
+  private draining = false;
+
+  private readonly DISPATCHED_MESSAGES_CAP = 5000;
+  private readonly COLD_START_WINDOW_MS: number;
+
+  constructor(private readonly opts: ParallGatewayOptions) {
+    this.COLD_START_WINDOW_MS = opts.coldStartWindowMs ?? 5 * 60_000;
+  }
+
+  async run(abortSignal: AbortSignal): Promise<void> {
+    const { ws, log } = this.opts;
+
+    ws.onStateChange((state) => {
+      log?.info(`parall[${this.opts.accountId}]: connection state → ${state}`);
+    });
+
+    ws.on("hello", async (data: HelloData) => {
+      await this.handleHello(data);
+    });
+
+    ws.on("chat.update", (data: ChatUpdateData) => {
+      const changes = data.changes as Record<string, unknown> | undefined;
+      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 as Chat["type"] } : {}),
+          ...(typeof changes.name === "string" ? { name: changes.name } : {}),
+          ...(typeof changes.agent_routing_mode === "string"
+            ? { agentRoutingMode: changes.agent_routing_mode as Chat["agent_routing_mode"] }
+            : {}),
+        });
+      } else if (typeof changes.type === "string") {
+        this.chatInfoMap.set(data.chat_id, {
+          type: changes.type as Chat["type"],
+          name: typeof changes.name === "string" ? changes.name : null,
+          agentRoutingMode: (typeof changes.agent_routing_mode === "string"
+            ? changes.agent_routing_mode
+            : "passive") as Chat["agent_routing_mode"],
+        });
+      }
+    });
+
+    ws.on("message.new", async (data: MessageNewData) => {
+      await this.handleMessage(data);
+    });
+
+    ws.on("agent_config.update", async (data: AgentConfigUpdateData) => {
+      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: TaskAssignedData) => {
+      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<void>((resolve) => {
+      abortSignal.addEventListener("abort", async () => {
+        await this.shutdown();
+        resolve();
+      });
+    });
+  }
+
+  private tryClaimMessage(id: string): boolean {
+    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;
+  }
+
+  private startTyping(chatId: string) {
+    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 });
+  }
+
+  private stopTyping(chatId: string) {
+    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");
+  }
+
+  private buildDispatchContext(event: ParallEvent, sessionKey: string): DispatchContext {
+    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,
+    };
+  }
+
+  private async createInputStep(event: ParallEvent) {
+    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)}`);
+    }
+  }
+
+  private async createRuntimeStep(event: ParallEvent, runtimeEvent: RuntimeEvent, stepIdFilePath?: string) {
+    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)}`);
+    }
+  }
+
+  private writeStepIdFile(filePath: string, stepId: string) {
+    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)}`);
+    }
+  }
+
+  private clearStepIdFile(filePath: string) {
+    try {
+      fs.writeFileSync(filePath, "", "utf8");
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
+
+  private async createInputStepsForEarlierEvents(events: ParallEvent[]) {
+    for (const event of events) {
+      await this.createInputStep(event);
+    }
+  }
+
+  private async runDispatch(
+    event: ParallEvent,
+    sessionKey: string,
+    bodyForAgent: string,
+    earlierEvents: ParallEvent[] = [],
+  ) {
+    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)}`);
+        }
+      }
+    }
+  }
+
+  private async runForkDrainLoop(fork: ActiveForkState) {
+    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: CleanupForkOpts = {
+          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);
+      }
+    }
+  }
+
+  private 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: ParallEvent = {
+            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: ParallEvent[] = [];
+        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;
+    }
+  }
+
+  private async handleInboundEvent(event: ParallEvent): Promise<boolean> {
+    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<boolean>((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: ActiveForkState = {
+          fork,
+          targetId: event.targetId,
+          queue: [],
+          processedEvents: [],
+        };
+        this.forkStates.set(event.targetId, activeFork);
+        this.dispatchState.activeForks.set(event.targetId, fork.sessionKey);
+
+        const firstEventPromise = new Promise<boolean>((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;
+      }
+    }
+  }
+
+  private async getOrFetchChatInfo(chatId: string): Promise<ChatInfo | null> {
+    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;
+    }
+  }
+
+  private async buildMessageDispatchDecision(
+    chatId: string,
+    message: DispatchableMessage,
+  ): Promise<MessageDispatchDecision> {
+    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: Record<string, string | undefined> = {};
+
+    if (message.message_type === "text") {
+      const content = message.content as TextContent;
+      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 as MediaContent;
+      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,
+      },
+    };
+  }
+
+  private async handleMessage(data: MessageNewData) {
+    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);
+    }
+  }
+
+  private async handleTaskAssignment(task: Task, ackSourceId?: string): Promise<boolean> {
+    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: ParallEvent = {
+      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;
+  }
+
+  private async catchUpFromDispatch(coldStart = false) {
+    const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
+    let cursor: string | undefined;
+    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: Awaited<ReturnType<typeof this.opts.client.getTask>> | null = null;
+            let taskFetchFailed = false;
+            try {
+              task = await this.opts.client.getTask(this.opts.config.org_id, item.task_id);
+            } catch (err: unknown) {
+              const status = (err as { status?: number })?.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: Awaited<ReturnType<typeof this.opts.client.getMessage>> | null = null;
+            let msgFetchFailed = false;
+            try {
+              msg = await this.opts.client.getMessage(item.source_id);
+            } catch (err: unknown) {
+              const status = (err as { status?: number })?.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)`);
+    }
+  }
+
+  private async handleHello(data: HelloData) {
+    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)}`);
+    }
+  }
+
+  private 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`);
+  }
+}