@parall/parall 1.12.0

package/src/gateway.ts

@@ -0,0 +1,1222 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+
+/** Extract ChannelGatewayAdapter from ChannelPlugin (removed from public SDK exports in 2026.3.24). */
+type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>["gateway"]>;
+import { ParallClient, ParallWs, MENTION_ALL_USER_ID } from "@parall/sdk";
+import type { Chat, MessageNewData, TextContent, MediaContent, HelloData, ChatUpdateData, AgentConfigUpdateData, TaskAssignedData, Task } from "@parall/sdk";
+import type { ParallChannelConfig } from "./types.js";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resolveParallAccount } from "./accounts.js";
+import {
+  getParallRuntime,
+  setParallAccountState,
+  getParallAccountState,
+  removeParallAccountState,
+  setSessionChatId,
+  setSessionMessageId,
+  setDispatchMessageId,
+  setDispatchGroupKey,
+  clearDispatchGroupKey,
+} from "./runtime.js";
+import type { ParallEvent, DispatchState, ForkResult } from "./runtime.js";
+import { buildOrchestratorSessionKey } from "./session.js";
+import type { ResolvedParallAccount } from "./types.js";
+import { fetchAndApplyPlatformConfig } from "./config-manager.js";
+import { startWikiHelper } from "./wiki-helper.js";
+import { routeTrigger, defaultRoutingStrategy } from "./routing.js";
+import { forkOrchestratorSession, cleanupForkSession, resolveTranscriptFile } from "./fork.js";
+
+function resolveWsUrl(account: ResolvedParallAccount): string {
+  if (account.config.ws_url) return account.config.ws_url;
+  const base = account.config.parall_url.replace(/\/$/, "");
+  const wsBase = base.replace(/^http/, "ws");
+  return `${wsBase}/ws`;
+}
+
+type ChatInfo = { type: Chat["type"]; name: string | null; agentRoutingMode: Chat["agent_routing_mode"] };
+
+/**
+ * Fetch all chats with pagination and populate the info map (type + name).
+ */
+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 c of res.data) {
+      chatInfoMap.set(c.id, { type: c.type, name: c.name ?? null, agentRoutingMode: c.agent_routing_mode });
+    }
+    total += res.data.length;
+    cursor = res.has_more ? res.next_cursor : undefined;
+  } while (cursor);
+  return total;
+}
+
+// ---------------------------------------------------------------------------
+// Event body formatting
+// ---------------------------------------------------------------------------
+
+function buildEventBody(event: ParallEvent): string {
+  const lines: string[] = [];
+  if (event.type === "message") {
+    lines.push(`[Event: message.new]`);
+    const chatLabel = event.targetName
+      ? `"${event.targetName}" (${event.targetId})`
+      : event.targetId;
+    lines.push(`[Chat: ${chatLabel} | type: ${event.targetType ?? "unknown"}]`);
+    lines.push(`[From: ${event.senderName} (${event.senderId})]`);
+    lines.push(`[Message ID: ${event.messageId}]`);
+    if (event.threadRootId) lines.push(`[Thread: ${event.threadRootId}]`);
+    if (event.noReply) lines.push(`[Hint: no_reply]`);
+    if (event.mediaFields?.MediaUrl) {
+      lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
+    }
+    lines.push("", event.body);
+  } else {
+    lines.push(`[Event: task.assigned]`);
+    const taskLabel = event.targetName
+      ? `${event.targetName} (${event.targetId})`
+      : event.targetId;
+    lines.push(`[Task: ${taskLabel} | type: ${event.targetType ?? "task"}]`);
+    lines.push(`[Assigned by: ${event.senderName} (${event.senderId})]`);
+    lines.push("", event.body);
+  }
+  return lines.join("\n");
+}
+
+function buildForkResultPrefix(results: ForkResult[]): string {
+  if (!results.length) return "";
+  const blocks = results.map((r) => {
+    const lines = [`[Fork result]`];
+    lines.push(`[Handled: ${r.sourceEvent.type} — ${r.sourceEvent.summary}]`);
+    if (r.actions.length) lines.push(`[Actions: ${r.actions.join("; ")}]`);
+    return lines.join("\n");
+  });
+  return blocks.join("\n\n") + "\n\n---\n\n";
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch to OpenClaw agent (orchestrator mode — all text suppressed)
+// ---------------------------------------------------------------------------
+
+async function dispatchToAgent(opts: {
+  core: PluginRuntime;
+  cfg: Record<string, unknown>;
+  client: ParallClient;
+  config: ParallChannelConfig;
+  agentUserId: string;
+  accountId: string;
+  sessionKey: string;
+  messageId: string;
+  inboundCtx: Record<string, unknown>;
+  triggerType?: string;
+  triggerRef?: Record<string, unknown>;
+  chatId?: string;
+  defaultTargetType?: string;
+  defaultTargetId?: string;
+  senderId?: string;
+  senderName?: string;
+  messageBody?: string;
+  log?: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}) {
+  const { core, cfg, client, config, agentUserId, accountId, sessionKey, messageId, inboundCtx, log } = opts;
+  const triggerType = opts.triggerType ?? "mention";
+  const triggerRef = opts.triggerRef ?? { message_id: messageId };
+
+  // Resolve session ID from account state
+  const state = getParallAccountState(accountId);
+  const sessionId = state?.activeSessionId;
+
+  // Entire dispatch lifecycle in one try/finally: active-set → input step → dispatch → idle.
+  // Note: fork-on-busy routing guarantees serial dispatch per session — concurrent
+  // dispatches to the same session should not happen in the orchestrator model.
+  let reasoningBuffer = "";
+  let turnGroupKey = "";
+  try {
+    // 1. Transition session to active FIRST (before any steps)
+    if (sessionId) {
+      try {
+        await client.updateAgentSession(config.org_id, agentUserId, sessionId, { status: "active" });
+      } catch (err) {
+        log?.warn(`parall[${accountId}]: failed to set session active: ${String(err)}`);
+      }
+    }
+
+    // 2. Create input step — captures the user message as a step in the session
+    if (sessionId) {
+      const targetType = opts.chatId ? "chat" : opts.defaultTargetType ?? "";
+      const targetId = opts.chatId ?? opts.defaultTargetId;
+      try {
+        await client.createAgentStep(config.org_id, agentUserId, sessionId, {
+          step_type: "input",
+          target_type: targetType,
+          target_id: targetId,
+          content: {
+            trigger_type: triggerType,
+            trigger_ref: triggerRef,
+            sender_id: opts.senderId ?? "",
+            sender_name: opts.senderName ?? "",
+            summary: opts.messageBody?.substring(0, 200) ?? "",
+          },
+        });
+      } catch (err) {
+        log?.warn(`parall[${accountId}]: failed to create input step: ${String(err)}`);
+      }
+    }
+
+    // 3. Dispatch to agent
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: inboundCtx,
+      cfg,
+      dispatcherOptions: {
+        deliver: async (payload: { text?: string }) => {
+          // Orchestrator mode: ALL text output is suppressed — agent uses tools to interact.
+          // Record as internal step for observability.
+          const replyText = payload.text?.trim();
+          if (!replyText || !sessionId) return;
+          const targetType = opts.chatId ? "chat" : opts.defaultTargetType ?? "";
+          const targetId = opts.chatId ?? opts.defaultTargetId;
+          try {
+            await client.createAgentStep(config.org_id, agentUserId, sessionId, {
+              step_type: "text",
+              target_type: targetType,
+              target_id: targetId,
+              content: { text: replyText, suppressed: true },
+            });
+          } catch (err) {
+            log?.warn(`parall[${accountId}]: failed to create suppressed text step: ${String(err)}`);
+          }
+        },
+        onReplyStart: () => {
+          // Generate a new group key per LLM response turn — shared across thinking + tool_call steps
+          turnGroupKey = crypto.randomUUID();
+          setDispatchGroupKey(sessionKey, turnGroupKey);
+        },
+      },
+      replyOptions: {
+        onReasoningStream: (payload: { text?: string }) => {
+          reasoningBuffer += payload.text ?? "";
+        },
+        onReasoningEnd: async () => {
+          if (sessionId && reasoningBuffer) {
+            const targetType = opts.chatId ? "chat" : opts.defaultTargetType ?? "";
+            const targetId = opts.chatId ?? opts.defaultTargetId;
+            try {
+              await client.createAgentStep(config.org_id, agentUserId, sessionId, {
+                step_type: "thinking",
+                target_type: targetType,
+                target_id: targetId,
+                content: { text: reasoningBuffer },
+                group_key: turnGroupKey || undefined,
+              });
+            } catch (err) {
+              log?.warn(`parall[${accountId}]: failed to create thinking step: ${String(err)}`);
+            }
+          }
+          reasoningBuffer = "";
+        },
+      },
+    });
+    return true;
+  } catch (err) {
+    log?.error(`parall[${accountId}]: dispatch failed for ${messageId}: ${String(err)}`);
+    return false;
+  } finally {
+    // Transition session back to idle after dispatch completes (or fails)
+    if (sessionId) {
+      try {
+        await client.updateAgentSession(config.org_id, agentUserId, sessionId, { status: "idle" });
+      } catch (err) {
+        log?.warn(`parall[${accountId}]: failed to set session idle: ${String(err)}`);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Gateway
+// ---------------------------------------------------------------------------
+
+export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
+  startAccount: async (ctx) => {
+    const account = resolveParallAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
+    if (!account.enabled) return;
+    if (!account.configured) throw new Error("Parall account is not configured: parall_url/api_key/org_id required");
+
+    const { config } = account;
+    const core = getParallRuntime();
+    const log = ctx.log;
+
+    const client = new ParallClient({
+      baseUrl: config.parall_url,
+      token: config.api_key,
+    });
+
+    // Resolve agent's own user ID
+    const me = await client.getMe();
+    const agentUserId = me.id;
+    log?.info(`parall[${ctx.accountId}]: authenticated as ${me.display_name} (${agentUserId})`);
+
+    // Apply platform config (models, defaults)
+    const stateDir = process.env.OPENCLAW_STATE_DIR
+      || path.join(process.env.HOME || "/data", ".openclaw");
+    const openclawConfigPath = path.join(stateDir, "openclaw.json");
+    const previousEnv = {
+      PRLL_API_URL: process.env.PRLL_API_URL,
+      PRLL_API_KEY: process.env.PRLL_API_KEY,
+      PRLL_ORG_ID: process.env.PRLL_ORG_ID,
+      PRLL_AGENT_ID: process.env.PRLL_AGENT_ID,
+    };
+    process.env.PRLL_API_URL = config.parall_url;
+    process.env.PRLL_API_KEY = config.api_key;
+    process.env.PRLL_ORG_ID = config.org_id;
+    process.env.PRLL_AGENT_ID = agentUserId;
+
+    const configManagerOpts = {
+      client,
+      stateDir,
+      configPath: openclawConfigPath,
+      credentials: { api_key: config.api_key, parall_url: config.parall_url },
+      log,
+    };
+
+    try {
+      await fetchAndApplyPlatformConfig(configManagerOpts);
+    } catch (err) {
+      log?.warn(`parall[${ctx.accountId}]: platform config fetch failed: ${String(err)}`);
+    }
+
+    let stopWikiHelper: (() => void) | null = null;
+    let wikiMountRoot: string | undefined;
+    try {
+      const wikiHelper = await startWikiHelper({
+        accountId: ctx.accountId,
+        parallUrl: config.parall_url,
+        apiKey: config.api_key,
+        orgId: config.org_id,
+        agentId: agentUserId,
+        stateDir,
+        log,
+      });
+      wikiMountRoot = wikiHelper.mountRoot;
+      stopWikiHelper = wikiHelper.stop;
+    } catch (err) {
+      log?.warn(`parall[${ctx.accountId}]: wiki helper startup failed: ${String(err)}`);
+    }
+
+    // Connect WebSocket via ticket auth (reconnection enabled by default in ParallWs)
+    const wsUrl = resolveWsUrl(account);
+    const ws = new ParallWs({
+      getTicket: () => client.getWsTicket(),
+      wsUrl,
+    });
+
+    // Orchestrator session key — single session for all Parall events
+    const orchestratorKey = buildOrchestratorSessionKey(ctx.accountId);
+
+    // Chat info lookup — populated on hello, used for structured event bodies
+    const chatInfoMap = new Map<string, ChatInfo>();
+
+    // Session ID from hello — used for heartbeat
+    let sessionId = "";
+    let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+    // Typing indicator management — reference-counted per chat
+    const activeDispatches = new Map<string, { count: number; typingTimer: ReturnType<typeof setInterval> }>();
+    // Dedupe task dispatches
+    const dispatchedTasks = new Set<string>();
+    // Dedupe message dispatches — shared by live handler and catch-up.
+    // Bounded: evict oldest entries when cap is reached.
+    const dispatchedMessages = new Set<string>();
+    const DISPATCHED_MESSAGES_CAP = 5000;
+    // Tracks whether the agent has had at least one successful hello in this process.
+    let hadSuccessfulHello = false;
+    const COLD_START_WINDOW_MS = 5 * 60_000;
+    // Heartbeat watchdog
+    let lastHeartbeatAt = Date.now();
+
+    /** Atomically claim a message ID for processing. Returns false if already claimed. */
+    function tryClaimMessage(id: string): boolean {
+      if (dispatchedMessages.has(id)) return false;
+      if (dispatchedMessages.size >= DISPATCHED_MESSAGES_CAP) {
+        let toEvict = Math.floor(DISPATCHED_MESSAGES_CAP / 4);
+        for (const old of dispatchedMessages) {
+          dispatchedMessages.delete(old);
+          if (--toEvict <= 0) break;
+        }
+      }
+      dispatchedMessages.add(id);
+      return true;
+    }
+
+    // Sessions dir for fork transcript resolution.
+    // Session key "agent:main:parall:..." → agentId is "main" → store at agents/main/sessions/
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+
+    // ---------------------------------------------------------------------------
+    // Dispatch state for fork-on-busy routing
+    // ---------------------------------------------------------------------------
+    const dispatchState: DispatchState = {
+      mainDispatching: false,
+      activeForks: new Map(),
+      pendingForkResults: [],
+      mainBuffer: [],
+    };
+
+    // ---------------------------------------------------------------------------
+    // Per-fork queue state (internal to gateway, not exposed via DispatchState)
+    // ---------------------------------------------------------------------------
+    type ForkQueueItem = {
+      event: ParallEvent;
+      resolve: (dispatched: boolean) => void;
+    };
+
+    type ActiveForkState = {
+      sessionKey: string;
+      sessionFile: string;
+      targetId: string;
+      queue: ForkQueueItem[];
+      processedEvents: ParallEvent[];
+    };
+
+    const forkStates = new Map<string, ActiveForkState>();
+
+    // ---------------------------------------------------------------------------
+    // Typing indicator helpers
+    // ---------------------------------------------------------------------------
+    function startTyping(chatId: string) {
+      const existing = activeDispatches.get(chatId);
+      if (existing) {
+        existing.count++;
+      } else {
+        if (ws.state === "connected") ws.sendTyping(chatId, "start");
+        const typingRefresh = setInterval(() => {
+          if (ws.state === "connected") ws.sendTyping(chatId, "start");
+        }, 2000);
+        activeDispatches.set(chatId, { count: 1, typingTimer: typingRefresh });
+      }
+    }
+
+    function stopTyping(chatId: string) {
+      const dispatch = activeDispatches.get(chatId);
+      if (!dispatch) return;
+      dispatch.count--;
+      if (dispatch.count <= 0) {
+        clearInterval(dispatch.typingTimer);
+        activeDispatches.delete(chatId);
+        if (ws.state === "connected") ws.sendTyping(chatId, "stop");
+      }
+    }
+
+    // ---------------------------------------------------------------------------
+    // Fork drain loop — processes queued events on a forked session
+    // ---------------------------------------------------------------------------
+
+    /**
+     * Process all queued events on a fork session with coalescing, then clean up.
+     * Fire-and-forget: callers await per-event promises, not this function.
+     *
+     * Coalescing: instead of dispatching events one-by-one, all queued events are
+     * merged into a single prompt and dispatched once — same pattern as drainMainBuffer.
+     *
+     * Invariant: between the while-loop empty check and cleanup, there is no
+     * await, so JS single-threaded execution guarantees no new events can be
+     * pushed to the queue between the check and the cleanup.
+     */
+    async function runForkDrainLoop(fork: ActiveForkState) {
+      try {
+        while (fork.queue.length > 0) {
+          // Take ALL queued items at once and coalesce via InboundHistory
+          const items = fork.queue.splice(0);
+          const events = items.map((it) => it.event);
+          const last = events[events.length - 1];
+          const earlier = events.slice(0, -1);
+          if (earlier.length) await createInputStepsForEarlierEvents(earlier);
+          const bodyForAgent = buildEventBody(last);
+          const inboundHistory = earlier.length ? buildInboundHistory(earlier) : undefined;
+          try {
+            await runDispatch(last, fork.sessionKey, bodyForAgent, inboundHistory);
+            fork.processedEvents.push(...events);
+            for (const it of items) it.resolve(true);
+          } catch (err) {
+            log?.error(`parall[${ctx.accountId}]: fork dispatch failed for ${last.messageId}: ${String(err)}`);
+            for (const it of items) it.resolve(false);
+            break;
+          }
+        }
+        // Resolve remaining items as not-dispatched (fork stopped after error).
+        // These events are NOT acked — dispatch retains them for catch-up replay.
+        for (const remaining of fork.queue.splice(0)) {
+          remaining.resolve(false);
+        }
+      } finally {
+        // Collect fork result for injection into main session's next turn
+        if (fork.processedEvents.length > 0) {
+          const first = fork.processedEvents[0];
+          dispatchState.pendingForkResults.push({
+            forkSessionKey: 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: [],
+          });
+        }
+        // Remove from tracking maps and clean up session files
+        forkStates.delete(fork.targetId);
+        dispatchState.activeForks.delete(fork.targetId);
+        cleanupForkSession({ sessionFile: fork.sessionFile, sessionKey: fork.sessionKey, sessionsDir });
+      }
+    }
+
+    // ---------------------------------------------------------------------------
+    // Build OpenClaw inbound context
+    // ---------------------------------------------------------------------------
+    function buildInboundCtx(
+      event: ParallEvent,
+      sessionKey: string,
+      bodyForAgent: string,
+      inboundHistory?: Array<{ sender: string; body: string; timestamp?: number }>,
+    ): Record<string, unknown> {
+      return core.channel.reply.finalizeInboundContext({
+        Body: event.body,
+        BodyForAgent: bodyForAgent,
+        RawBody: event.body,
+        CommandBody: event.body,
+        ...(event.mediaFields ?? {}),
+        ...(inboundHistory?.length ? { InboundHistory: inboundHistory } : {}),
+        From: `parall:${event.senderId}`,
+        To: `parall:orchestrator`,
+        SessionKey: sessionKey,
+        AccountId: ctx.accountId,
+        ChatType: event.targetType ?? "unknown",
+        SenderName: event.senderName,
+        SenderId: event.senderId,
+        Provider: "parall" as const,
+        Surface: "parall" as const,
+        MessageSid: event.messageId,
+        Timestamp: Date.now(),
+        CommandAuthorized: true,
+        OriginatingChannel: "parall" as const,
+        OriginatingTo: `parall:orchestrator`,
+      });
+    }
+
+    // ---------------------------------------------------------------------------
+    // Input step + InboundHistory helpers for coalesced events
+    // ---------------------------------------------------------------------------
+
+    /** Create input steps for earlier events in a coalesced batch (observability). */
+    async function createInputStepsForEarlierEvents(events: ParallEvent[]) {
+      const state = getParallAccountState(ctx.accountId);
+      const sessionId = state?.activeSessionId;
+      if (!sessionId) return;
+      await Promise.allSettled(events.map((ev) => {
+        const targetType = ev.targetId.startsWith("cht_") ? "chat" : ev.type === "task" ? "task" : "";
+        const triggerType = ev.type === "task" ? "task_assign" : "mention";
+        const triggerRef = ev.type === "task" ? { task_id: ev.targetId } : { message_id: ev.messageId };
+        return client.createAgentStep(config.org_id, agentUserId, sessionId, {
+          step_type: "input",
+          target_type: targetType,
+          target_id: ev.targetId.startsWith("cht_") ? ev.targetId : ev.type === "task" ? ev.targetId : undefined,
+          content: {
+            trigger_type: triggerType,
+            trigger_ref: triggerRef,
+            sender_id: ev.senderId,
+            sender_name: ev.senderName,
+            summary: ev.body.substring(0, 200),
+          },
+        }).catch((err: unknown) => {
+          log?.warn(`parall[${ctx.accountId}]: failed to create input step for ${ev.messageId}: ${String(err)}`);
+        });
+      }));
+    }
+
+    /** Build InboundHistory array from earlier events (for OpenClaw native context injection). */
+    function buildInboundHistory(events: ParallEvent[]): Array<{ sender: string; body: string }> {
+      return events.map((ev) => {
+        // Include metadata that would otherwise be lost in the plain body
+        const meta: string[] = [];
+        meta.push(`[Message ID: ${ev.messageId}]`);
+        if (ev.noReply) meta.push(`[Hint: no_reply]`);
+        if (ev.threadRootId) meta.push(`[Thread: ${ev.threadRootId}]`);
+        if (ev.mediaFields?.MediaUrl) {
+          meta.push(`[Attachment: ${ev.mediaFields.MediaType ?? "file"} ${ev.mediaFields.MediaUrl}]`);
+        }
+        return {
+          sender: ev.senderName,
+          body: meta.length ? `${meta.join(" ")}\n${ev.body}` : ev.body,
+        };
+      });
+    }
+
+    // ---------------------------------------------------------------------------
+    // Core dispatch: route event to main or fork session
+    // ---------------------------------------------------------------------------
+    async function runDispatch(
+      event: ParallEvent,
+      sessionKey: string,
+      bodyForAgent: string,
+      inboundHistory?: Array<{ sender: string; body: string; timestamp?: number }>,
+    ) {
+      // Set provenance maps for wiki tools
+      setSessionChatId(sessionKey, event.targetId);
+      setSessionMessageId(sessionKey, event.messageId);
+      setDispatchMessageId(sessionKey, event.messageId);
+
+      const inboundCtx = buildInboundCtx(event, sessionKey, bodyForAgent, inboundHistory);
+      const triggerType = event.type === "task" ? "task_assign" : "mention";
+      const triggerRef = event.type === "task"
+        ? { task_id: event.targetId }
+        : { message_id: event.messageId };
+      const isTask = event.type === "task";
+
+      const ok = await dispatchToAgent({
+        core,
+        cfg: ctx.cfg,
+        client,
+        config,
+        agentUserId,
+        accountId: ctx.accountId,
+        sessionKey,
+        messageId: event.messageId,
+        inboundCtx,
+        triggerType,
+        triggerRef,
+        chatId: event.targetId.startsWith("cht_") ? event.targetId : undefined,
+        defaultTargetType: isTask ? "task" : undefined,
+        defaultTargetId: isTask ? event.targetId : undefined,
+        senderId: event.senderId,
+        senderName: event.senderName,
+        messageBody: event.body,
+        log,
+      });
+      if (!ok) throw new Error(`dispatch failed for ${event.messageId}`);
+    }
+
+    /**
+     * Drain buffered events into main session with coalescing.
+     * When multiple events accumulate while main is busy, they are merged into a
+     * single combined prompt and dispatched once (one AgentRun), so the agent sees
+     * the full context instead of replying to stale messages one by one.
+     *
+     * IMPORTANT: Caller must hold mainDispatching=true. This function keeps the flag
+     * raised throughout the drain to prevent re-entrance from concurrent event handlers.
+     * The flag is only lowered when the buffer is fully exhausted.
+     */
+    let draining = false;
+    async function drainMainBuffer() {
+      // Re-entrance guard: if we're already draining (e.g. fork completed during
+      // a drain iteration), the outer loop will pick up new items naturally.
+      if (draining) return;
+      draining = true;
+      try {
+        while (dispatchState.mainBuffer.length > 0 || dispatchState.pendingForkResults.length > 0) {
+          // If we only have fork results but no events, create a synthetic wake-up
+          if (dispatchState.mainBuffer.length === 0 && dispatchState.pendingForkResults.length > 0) {
+            const forkPrefix = buildForkResultPrefix(dispatchState.pendingForkResults.splice(0));
+            const syntheticEvent: ParallEvent = {
+              type: "message",
+              targetId: "_orchestrator",
+              targetType: "system",
+              senderId: "system",
+              senderName: "system",
+              messageId: `synthetic-${Date.now()}`,
+              body: "[Orchestrator: fork session(s) completed — review results above]",
+            };
+            const bodyForAgent = forkPrefix + buildEventBody(syntheticEvent);
+            dispatchState.mainCurrentTargetId = undefined;
+            await runDispatch(syntheticEvent, orchestratorKey, bodyForAgent);
+            continue;
+          }
+
+          // Coalesce same-target events; leave other targets for the next iteration.
+          // Under backpressure (max forks), the buffer may contain mixed targets —
+          // coalescing across targets would couple unrelated provenance/noReply.
+          const targetId = dispatchState.mainBuffer[0].targetId;
+          const events: ParallEvent[] = [];
+          const rest: ParallEvent[] = [];
+          for (const ev of dispatchState.mainBuffer.splice(0)) {
+            (ev.targetId === targetId ? events : rest).push(ev);
+          }
+          dispatchState.mainBuffer.push(...rest);
+
+          const last = events[events.length - 1];
+          const earlier = events.slice(0, -1);
+
+          // Create input steps for earlier events (observability), then dispatch
+          // last event with InboundHistory populated from earlier events.
+          if (earlier.length) await createInputStepsForEarlierEvents(earlier);
+
+          const forkPrefix = buildForkResultPrefix(dispatchState.pendingForkResults.splice(0));
+          const bodyForAgent = forkPrefix + buildEventBody(last);
+          const inboundHistory = earlier.length ? buildInboundHistory(earlier) : undefined;
+
+          dispatchState.mainCurrentTargetId = last.targetId;
+          await runDispatch(last, orchestratorKey, bodyForAgent, inboundHistory);
+          // Ack all coalesced events
+          for (const ev of events) {
+            const sourceType = ev.type === "task" ? "task_activity" : "message";
+            client.ackDispatch(config.org_id, { source_type: sourceType, source_id: ev.messageId }).catch(() => {});
+          }
+        }
+      } finally {
+        draining = false;
+        dispatchState.mainDispatching = false;
+        dispatchState.mainCurrentTargetId = undefined;
+      }
+    }
+
+    /**
+     * Route and dispatch an inbound event.
+     * Returns true if the event was dispatched (main or fork), false if only buffered.
+     * Callers should only ack dispatch when this returns true — buffered events may be
+     * lost on crash and need to be replayed from dispatch on the next catch-up.
+     */
+    async function handleInboundEvent(event: ParallEvent): Promise<boolean> {
+      const disposition = routeTrigger(event, dispatchState, defaultRoutingStrategy);
+
+      switch (disposition.action) {
+        case "main": {
+          // Main session is idle — dispatch directly.
+          // Set mainDispatching BEFORE the await and keep it raised through
+          // drainMainBuffer() so no concurrent event can enter this case.
+          // drainMainBuffer() lowers the flag when the buffer is fully exhausted.
+          const forkPrefix = buildForkResultPrefix(dispatchState.pendingForkResults.splice(0));
+          const bodyForAgent = forkPrefix + buildEventBody(event);
+
+          dispatchState.mainDispatching = true;
+          dispatchState.mainCurrentTargetId = event.targetId;
+          try {
+            await runDispatch(event, orchestratorKey, bodyForAgent);
+          } finally {
+            // Drain any events that buffered while we were dispatching.
+            // mainDispatching stays true — drainMainBuffer owns releasing it.
+            await drainMainBuffer();
+          }
+          return true;
+        }
+
+        case "buffer-main":
+          dispatchState.mainBuffer.push(event);
+          return false;
+
+        case "buffer-fork": {
+          // Push event into the existing fork's queue. The fork drain loop will
+          // process it and resolve the promise when done. If the fork was cleaned
+          // up between the routing decision and here (race), fallback to buffer-main.
+          const activeFork = forkStates.get(event.targetId);
+          if (!activeFork) {
+            dispatchState.mainBuffer.push(event);
+            return false;
+          }
+          return new Promise<boolean>((resolve) => {
+            activeFork.queue.push({ event, resolve });
+          });
+        }
+
+        case "new-fork": {
+          // Fork the orchestrator's transcript and dispatch in parallel.
+          const transcriptFile = resolveTranscriptFile(sessionsDir, orchestratorKey);
+          const fork = transcriptFile
+            ? forkOrchestratorSession({
+                orchestratorSessionKey: orchestratorKey,
+                accountId: ctx.accountId,
+                transcriptFile,
+                sessionsDir,
+              })
+            : null;
+
+          if (fork) {
+            const activeFork: ActiveForkState = {
+              sessionKey: fork.sessionKey,
+              sessionFile: fork.sessionFile,
+              targetId: event.targetId,
+              queue: [],
+              processedEvents: [],
+            };
+            forkStates.set(event.targetId, activeFork);
+            dispatchState.activeForks.set(event.targetId, fork.sessionKey);
+
+            // Create promise for the first event, then start the drain loop
+            const firstEventPromise = new Promise<boolean>((resolve) => {
+              activeFork.queue.push({ event, resolve });
+            });
+            // Fire-and-forget — drain loop runs concurrently, callers await per-event promises
+            runForkDrainLoop(activeFork).catch((err) => {
+              log?.error(`parall[${ctx.accountId}]: fork drain loop error: ${String(err)}`);
+            });
+            return firstEventPromise;
+          } else {
+            log?.warn(`parall[${ctx.accountId}]: fork failed, buffering event for main session`);
+            dispatchState.mainBuffer.push(event);
+            return false;
+          }
+        }
+      }
+      return false;
+    }
+
+    // ---------------------------------------------------------------------------
+    // WebSocket event handlers
+    // ---------------------------------------------------------------------------
+
+    ws.onStateChange((state) => {
+      log?.info(`parall[${ctx.accountId}]: connection state → ${state}`);
+    });
+
+    ws.on("hello", async (data: HelloData) => {
+      sessionId = data.session_id ?? "";
+      const intervalSec = data.heartbeat_interval > 0 ? data.heartbeat_interval : 30;
+      try {
+        const count = await fetchAllChats(client, config.org_id, chatInfoMap);
+        log?.info(`parall[${ctx.accountId}]: WebSocket connected, ${count} chats cached`);
+
+        // Create AgentSession on first hello (session lives across dispatches).
+        // On WS reconnect, preserve the existing session — only create if none exists.
+        const existingState = getParallAccountState(ctx.accountId);
+        let activeSessionId: string | undefined = existingState?.activeSessionId;
+        if (!activeSessionId) {
+          try {
+            const session = await client.createAgentSession(config.org_id, agentUserId, {
+              runtime_type: "openclaw",
+              runtime_key: orchestratorKey,
+              runtime_ref: { hostname: os.hostname(), pid: process.pid },
+            });
+            activeSessionId = session.id;
+            log?.info(`parall[${ctx.accountId}]: created agent session ${session.id}`);
+          } catch (err) {
+            log?.warn(`parall[${ctx.accountId}]: failed to create agent session: ${String(err)}`);
+          }
+        }
+
+        setParallAccountState(ctx.accountId, {
+          client,
+          orgId: config.org_id,
+          agentUserId,
+          activeSessionId,
+          wikiMountRoot,
+          ws,
+          orchestratorSessionKey: orchestratorKey,
+        });
+
+        // (Re)start heartbeat
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        lastHeartbeatAt = Date.now();
+        heartbeatTimer = setInterval(() => {
+          const now = Date.now();
+          const expectedMs = intervalSec * 1000;
+          const drift = now - lastHeartbeatAt - expectedMs;
+          if (drift > 15000) {
+            log?.warn(`parall[${ctx.accountId}]: heartbeat drift ${drift}ms — event loop may be blocked`);
+          }
+          lastHeartbeatAt = now;
+          if (ws.state !== "connected") return;
+          ws.sendAgentHeartbeat(sessionId, {
+            hostname: os.hostname(),
+            cores: os.cpus().length,
+            mem_total: os.totalmem(),
+            mem_free: os.freemem(),
+            uptime: os.uptime(),
+          });
+        }, intervalSec * 1000);
+
+        // Dispatch catch-up: fetch pending dispatch events (FIFO).
+        // On cold start, skip items older than COLD_START_WINDOW_MS to avoid
+        // replaying historical backlog from a previous process.
+        const isFirstHello = !hadSuccessfulHello;
+        hadSuccessfulHello = true;
+        catchUpFromDispatch(isFirstHello).catch((err) => {
+          log?.warn(`parall[${ctx.accountId}]: dispatch catch-up failed: ${String(err)}`);
+        });
+      } catch (err) {
+        log?.error(`parall[${ctx.accountId}]: failed to fetch chats: ${String(err)}`);
+      }
+    });
+
+    ws.on("chat.update", (data: ChatUpdateData) => {
+      const changes = data.changes as Record<string, unknown> | undefined;
+      if (!changes) return;
+      const existing = chatInfoMap.get(data.chat_id);
+      if (existing) {
+        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") {
+        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"],
+        });
+      }
+    });
+
+    // Handle inbound messages (text + file)
+    ws.on("message.new", async (data: MessageNewData) => {
+      if (data.sender_id === agentUserId) return;
+      if (data.message_type !== "text" && data.message_type !== "file") return;
+      // Dedupe: claim this message so catch-up won't re-dispatch it
+      if (!tryClaimMessage(data.id)) return;
+
+      const chatId = data.chat_id;
+
+      // Resolve chat info — query API for unknown chats
+      let chatInfo = chatInfoMap.get(chatId);
+      if (!chatInfo) {
+        try {
+          const chat = await client.getChat(config.org_id, chatId);
+          chatInfo = { type: chat.type, name: chat.name ?? null, agentRoutingMode: chat.agent_routing_mode };
+          chatInfoMap.set(chatId, chatInfo);
+        } catch (err) {
+          log?.warn(`parall[${ctx.accountId}]: failed to resolve chat for ${chatId}, skipping: ${String(err)}`);
+          return;
+        }
+      }
+
+      // Build body text and optional media fields
+      let body = "";
+      let mediaFields: Record<string, string | undefined> = {};
+
+      if (data.message_type === "text") {
+        const content = data.content as TextContent;
+        body = content.text?.trim() ?? "";
+        if (!body) return;
+
+        // In group chats, respond based on agent_routing_mode:
+        // - passive (default): only when @mentioned or @all
+        // - active: all messages dispatched via live handler
+        // - smart: skip live handler — server decides routing via inbox items
+        if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+          const mentions = content.mentions ?? [];
+          const isMentioned = mentions.some(
+            (m) => m.user_id === agentUserId || m.user_id === MENTION_ALL_USER_ID,
+          );
+          if (!isMentioned) {
+            // Release claim so catch-up can process this via dispatch events
+            dispatchedMessages.delete(data.id);
+            return;
+          }
+        }
+      } else {
+        const content = data.content as MediaContent;
+        if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+          dispatchedMessages.delete(data.id);
+          return;
+        }
+        body = content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`;
+        if (content.attachment_id) {
+          try {
+            const fileRes = await client.getFileUrl(content.attachment_id);
+            mediaFields = { MediaUrl: fileRes.url, MediaType: content.mime_type };
+          } catch (err) {
+            log?.warn(`parall[${ctx.accountId}]: failed to get file URL for ${content.attachment_id}: ${String(err)}`);
+          }
+        }
+      }
+
+      const event: ParallEvent = {
+        type: "message",
+        targetId: chatId,
+        targetName: chatInfo.name ?? undefined,
+        targetType: chatInfo.type,
+        senderId: data.sender_id,
+        senderName: data.sender?.display_name ?? data.sender_id,
+        messageId: data.id,
+        body,
+        threadRootId: data.thread_root_id ?? undefined,
+        noReply: data.hints?.no_reply ?? false,
+        mediaFields: Object.keys(mediaFields).length > 0 ? mediaFields : undefined,
+      };
+
+      // Start typing for UX feedback. For buffer-main events (main is busy with
+      // same target), typing persists until the buffer drains.
+      // For fork events, typing persists until the fork dispatch completes.
+      // Both handleInboundEvent paths await their dispatches, so finally works correctly.
+      const willDispatch = !dispatchState.mainDispatching || dispatchState.mainCurrentTargetId !== chatId;
+      if (willDispatch) startTyping(chatId);
+      try {
+        const dispatched = await handleInboundEvent(event);
+        if (dispatched) {
+          client.ackDispatch(config.org_id, { source_type: "message", source_id: data.id }).catch(() => {});
+        } else {
+          // Not dispatched (buffered or fork failed) — release claim so catch-up can retry
+          dispatchedMessages.delete(data.id);
+        }
+      } catch (err) {
+        log?.error(`parall[${ctx.accountId}]: event dispatch failed for ${data.id}: ${String(err)}`);
+        dispatchedMessages.delete(data.id);
+      } finally {
+        if (willDispatch) stopTyping(chatId);
+      }
+    });
+
+    // Re-apply platform config on server push
+    ws.on("agent_config.update", async (data: AgentConfigUpdateData) => {
+      log?.info(`parall[${ctx.accountId}]: config update notification (version=${data.version})`);
+      try {
+        await fetchAndApplyPlatformConfig(configManagerOpts);
+      } catch (err) {
+        log?.warn(`parall[${ctx.accountId}]: config update failed: ${String(err)}`);
+      }
+    });
+
+    // Task assignment handler
+    async function handleTaskAssignment(task: Task): Promise<boolean> {
+      const dedupeKey = `${task.id}:${task.updated_at}`;
+      if (dispatchedTasks.has(dedupeKey)) {
+        log?.info(`parall[${ctx.accountId}]: skipping already-dispatched task ${task.identifier ?? task.id}`);
+        return false;
+      }
+      dispatchedTasks.add(dedupeKey);
+      log?.info(`parall[${ctx.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"),
+      };
+
+      const dispatched = await handleInboundEvent(event);
+      if (!dispatched) {
+        // Buffered, not yet dispatched — release dedupe so catch-up can retry
+        dispatchedTasks.delete(dedupeKey);
+      }
+      return dispatched;
+    }
+
+    // Server event buffer overflowed — events were lost, trigger full catch-up
+    ws.on("recovery.overflow", () => {
+      log?.warn(`parall[${ctx.accountId}]: recovery.overflow — triggering full catch-up`);
+      catchUpFromDispatch().catch((err) =>
+        log?.warn(`parall[${ctx.accountId}]: overflow catch-up failed: ${String(err)}`));
+    });
+
+    ws.on("task.assigned", async (data: TaskAssignedData) => {
+      if (data.assignee_id !== agentUserId) return;
+      if (data.status !== "todo" && data.status !== "in_progress") return;
+      try {
+        const dispatched = await handleTaskAssignment(data);
+        if (dispatched) {
+          client.ackDispatch(config.org_id, { source_type: "task_activity", source_id: data.id }).catch(() => {});
+        }
+      } catch (err) {
+        log?.error(`parall[${ctx.accountId}]: task dispatch failed for ${data.id}: ${String(err)}`);
+      }
+    });
+
+    // ── Dispatch catch-up ──
+    // Replays missed events via the dispatch API (agent-only endpoint, FIFO order).
+    // Each dispatch event is a source-pointer; we re-fetch the entity to build a ParallEvent.
+    //
+    // Cold-start window: On a fresh process start (not reconnect), events older than
+    // COLD_START_WINDOW_MS are acked without processing. This is an intentional operator
+    // decision: a newly started agent should not replay unbounded historical backlog from
+    // a previous process lifetime. Reconnects (non-cold-start) replay all pending events.
+    //
+    // NOTE: RouteToAgents (active/smart group routing) inserts dispatch rows asynchronously
+    // after the message.new WS event. A race exists where the live ack-by-source fires
+    // before the dispatch row is inserted, leaving an orphan pending row. This is benign:
+    // catch-up will process it on next cycle (duplicate delivery, not data loss).
+    // TODO: resolve by creating dispatch rows before publishing the live event, or by
+    // consuming dispatch.new in the live path.
+    async function catchUpFromDispatch(coldStart = false) {
+      const minAge = coldStart ? Date.now() - COLD_START_WINDOW_MS : 0;
+      let cursor: string | undefined;
+      let processed = 0;
+      let skippedOld = 0;
+
+      do {
+        const page = await client.getDispatch(config.org_id, {
+          limit: 50,
+          cursor,
+        });
+
+        for (const item of page.data ?? []) {
+          if (minAge > 0 && new Date(item.created_at).getTime() < minAge) {
+            client.ackDispatchByID(config.org_id, item.id).catch(() => {});
+            skippedOld++;
+            continue;
+          }
+
+          processed++;
+          try {
+            let dispatched = false;
+            if (item.event_type === "task_assign" && item.task_id) {
+              // Task catch-up: fetch full task and dispatch
+              let task: Awaited<ReturnType<typeof client.getTask>> | null = null;
+              let taskFetchFailed = false;
+              try {
+                task = await client.getTask(config.org_id, item.task_id);
+              } catch (err: unknown) {
+                // Distinguish 404 (task deleted) from transient failures
+                const status = (err as { status?: number })?.status;
+                if (status === 404) {
+                  task = null; // task genuinely deleted
+                } else {
+                  taskFetchFailed = true;
+                  log?.warn(`parall[${ctx.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+                }
+              }
+              if (taskFetchFailed) {
+                continue; // leave pending for next catch-up cycle
+              }
+              if (task) {
+                // Defense-in-depth (D2): verify task is still assigned to this agent
+                if (task.assignee_id !== agentUserId) {
+                  log?.info(`parall[${ctx.accountId}]: skipping stale task dispatch ${item.id} — reassigned to ${task.assignee_id}`);
+                  client.ackDispatchByID(config.org_id, item.id).catch(() => {});
+                  continue;
+                }
+                dispatched = await handleTaskAssignment(task);
+              } else {
+                dispatched = true; // task genuinely deleted — ack to prevent infinite retry
+              }
+            } else if (item.event_type === "message" && item.source_id && item.chat_id) {
+              // Message catch-up: build ParallEvent from dispatch source pointer
+              if (!tryClaimMessage(item.source_id)) continue;
+              let msg: Awaited<ReturnType<typeof client.getMessage>> | null = null;
+              let msgFetchFailed = false;
+              try {
+                msg = await client.getMessage(item.source_id);
+              } catch (err: unknown) {
+                const status = (err as { status?: number })?.status;
+                if (status === 404) {
+                  msg = null; // message genuinely deleted
+                } else {
+                  msgFetchFailed = true;
+                  log?.warn(`parall[${ctx.accountId}]: catch-up message fetch failed for ${item.source_id}, leaving pending: ${String(err)}`);
+                }
+              }
+              if (msgFetchFailed) {
+                dispatchedMessages.delete(item.source_id);
+                continue; // leave pending for next catch-up cycle
+              }
+              if (!msg || msg.sender_id === agentUserId) {
+                dispatchedMessages.delete(item.source_id);
+                client.ackDispatchByID(config.org_id, item.id).catch(() => {});
+                continue;
+              }
+
+              let chatInfo = chatInfoMap.get(item.chat_id);
+              if (!chatInfo) {
+                try {
+                  const chat = await client.getChat(config.org_id, item.chat_id);
+                  chatInfo = { type: chat.type, name: chat.name ?? null, agentRoutingMode: chat.agent_routing_mode };
+                  chatInfoMap.set(item.chat_id, chatInfo);
+                } catch {
+                  dispatchedMessages.delete(item.source_id);
+                  continue;
+                }
+              }
+
+              let body = "";
+              let catchUpMediaFields: Record<string, string | undefined> = {};
+              if (msg.message_type === "text") {
+                body = (msg.content as TextContent).text?.trim() ?? "";
+              } else if (msg.message_type === "file") {
+                const fc = msg.content as MediaContent;
+                body = fc.caption?.trim() || `[file: ${fc.file_name || "attachment"}]`;
+                if (fc.attachment_id) {
+                  try {
+                    const fileRes = await client.getFileUrl(fc.attachment_id);
+                    catchUpMediaFields = { MediaUrl: fileRes.url, MediaType: fc.mime_type };
+                  } catch { /* degrade gracefully */ }
+                }
+              }
+              if (!body) {
+                dispatchedMessages.delete(item.source_id);
+                client.ackDispatchByID(config.org_id, item.id).catch(() => {});
+                continue;
+              }
+
+              const event: ParallEvent = {
+                type: "message",
+                targetId: item.chat_id,
+                targetName: chatInfo.name ?? undefined,
+                targetType: chatInfo.type,
+                senderId: msg.sender_id,
+                senderName: msg.sender?.display_name ?? msg.sender_id,
+                messageId: msg.id,
+                body,
+                threadRootId: msg.thread_root_id ?? undefined,
+                noReply: msg.hints?.no_reply ?? false,
+                mediaFields: Object.keys(catchUpMediaFields).length > 0 ? catchUpMediaFields : undefined,
+              };
+              dispatched = await handleInboundEvent(event);
+            }
+            if (dispatched) {
+              client.ackDispatchByID(config.org_id, item.id).catch(() => {});
+            }
+          } catch (err) {
+            log?.warn(`parall[${ctx.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) {
+        log?.info(`parall[${ctx.accountId}]: dispatch catch-up: processed ${processed}, skipped ${skippedOld} old item(s)`);
+      }
+    }
+
+    log?.info(`parall[${ctx.accountId}]: connecting to ${wsUrl}...`);
+    await ws.connect();
+
+    // Keep the gateway alive until aborted; clean up before resolving
+    return new Promise<void>((resolve) => {
+      ctx.abortSignal.addEventListener("abort", async () => {
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        for (const [, dispatch] of activeDispatches) {
+          clearInterval(dispatch.typingTimer);
+        }
+        activeDispatches.clear();
+        stopWikiHelper?.();
+
+        // Complete the agent session
+        const currentState = getParallAccountState(ctx.accountId);
+        if (currentState?.activeSessionId) {
+          try {
+            await client.updateAgentSession(config.org_id, agentUserId, currentState.activeSessionId, {
+              status: "completed",
+            });
+          } catch (err) {
+            log?.warn(`parall[${ctx.accountId}]: failed to complete session: ${String(err)}`);
+          }
+        }
+
+        ws.disconnect();
+        removeParallAccountState(ctx.accountId);
+        for (const [key, value] of Object.entries(previousEnv)) {
+          if (value === undefined) {
+            delete process.env[key];
+          } else {
+            process.env[key] = value;
+          }
+        }
+        log?.info(`parall[${ctx.accountId}]: disconnected`);
+        resolve();
+      });
+    });
+  },
+};