@parall/parall 1.12.0 → 1.13.1

package/src/gateway.ts

@@ -3,8 +3,13 @@ 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 {
+  ParallAgentGateway,
+  type DispatchAdapter,
+  type ParallEvent,
+  type RuntimeEvent,
+} from "@parall/agent-core";
+import { ParallClient, ParallWs } from "@parall/sdk";
 import type { ParallChannelConfig } from "./types.js";
 import * as crypto from "node:crypto";
 import * as os from "node:os";
@@ -12,22 +17,15 @@ import * as path from "node:path";
 import { resolveParallAccount } from "./accounts.js";
 import {
   getParallRuntime,
-  setParallAccountState,
-  getParallAccountState,
   removeParallAccountState,
-  setSessionChatId,
-  setSessionMessageId,
-  setDispatchMessageId,
   setDispatchGroupKey,
-  clearDispatchGroupKey,
+  setParallAccountState,
 } 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";
+import { cleanupForkSession, forkOrchestratorSession, resolveTranscriptFile } from "./fork.js";
 
 function resolveWsUrl(account: ResolvedParallAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
@@ -36,213 +34,186 @@ function resolveWsUrl(account: ResolvedParallAccount): string {
   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;
+function buildInboundCtx(
+  core: PluginRuntime,
+  accountId: string,
+  event: ParallEvent,
+  sessionKey: string,
+  bodyForAgent: string,
+  earlierEvents: ParallEvent[] = [],
+): Record<string, unknown> {
+  const inboundHistory = earlierEvents.length > 0 ? buildInboundHistory(earlierEvents) : undefined;
+  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: 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`,
+  });
 }
 
-// ---------------------------------------------------------------------------
-// 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]`);
+function buildInboundHistory(events: ParallEvent[]): Array<{ sender: string; body: string }> {
+  return events.map((event) => {
+    const meta: string[] = [];
+    meta.push(`[Message ID: ${event.messageId}]`);
+    if (event.noReply) meta.push(`[Hint: no_reply]`);
+    if (event.threadRootId) meta.push(`[Thread: ${event.threadRootId}]`);
     if (event.mediaFields?.MediaUrl) {
-      lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
+      meta.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 {
+      sender: event.senderName,
+      body: meta.length > 0 ? `${meta.join(" ")}\n${event.body}` : event.body,
+    };
   });
-  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)}`);
+function createRuntimeEventStream() {
+  const queue: RuntimeEvent[] = [];
+  const waiters: Array<{
+    resolve: (value: RuntimeEvent | undefined) => void;
+    reject: (reason?: unknown) => void;
+  }> = [];
+  let done = false;
+  let failure: unknown;
+
+  function flush() {
+    while (waiters.length > 0) {
+      if (failure) {
+        waiters.shift()!.reject(failure);
+        continue;
+      }
+      if (queue.length > 0) {
+        waiters.shift()!.resolve(queue.shift());
+        continue;
+      }
+      if (done) {
+        waiters.shift()!.resolve(undefined);
+        continue;
       }
+      break;
     }
+  }
 
-    // 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) ?? "",
-          },
+  return {
+    push(event: RuntimeEvent) {
+      queue.push(event);
+      flush();
+    },
+    end() {
+      done = true;
+      flush();
+    },
+    fail(err: unknown) {
+      failure = err;
+      flush();
+    },
+    async *stream(): AsyncGenerator<RuntimeEvent> {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift()!;
+          continue;
+        }
+        if (failure) throw failure;
+        if (done) return;
+
+        const next = await new Promise<RuntimeEvent | undefined>((resolve, reject) => {
+          waiters.push({ resolve, reject });
         });
-      } catch (err) {
-        log?.warn(`parall[${accountId}]: failed to create input step: ${String(err)}`);
+        if (!next) return;
+        yield next;
       }
-    }
+    },
+  };
+}
 
-    // 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 },
+function createOpenClawDispatchAdapter(opts: {
+  core: PluginRuntime;
+  cfg: Record<string, unknown>;
+  accountId: string;
+  sessionsDir: string;
+}): DispatchAdapter {
+  return {
+    async *dispatch({ event, earlierEvents = [], bodyForAgent, sessionKey }) {
+      const stream = createRuntimeEventStream();
+      let reasoningBuffer = "";
+      let turnGroupKey = "";
+
+      const run = opts.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: buildInboundCtx(opts.core, opts.accountId, event, sessionKey, bodyForAgent, earlierEvents),
+        cfg: opts.cfg,
+        dispatcherOptions: {
+          deliver: async (payload: { text?: string }) => {
+            const replyText = payload.text?.trim();
+            if (!replyText) return;
+            stream.push({
+              type: "text",
+              text: replyText,
+              project: false,
+              groupKey: turnGroupKey || undefined,
             });
-          } 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 ?? "";
+          },
+          onReplyStart: () => {
+            turnGroupKey = crypto.randomUUID();
+            setDispatchGroupKey(sessionKey, turnGroupKey);
+          },
         },
-        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 = "";
+        replyOptions: {
+          onReasoningStream: (payload: { text?: string }) => {
+            reasoningBuffer += payload.text ?? "";
+          },
+          onReasoningEnd: async () => {
+            if (!reasoningBuffer) return;
+            stream.push({
+              type: "thinking",
+              text: reasoningBuffer,
+              groupKey: turnGroupKey || undefined,
+            });
+            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
-// ---------------------------------------------------------------------------
+      run.then(() => stream.end()).catch((err) => stream.fail(err));
+      yield* stream.stream();
+    },
+
+    forkSession({ sessionKey }) {
+      const transcriptFile = resolveTranscriptFile(opts.sessionsDir, sessionKey);
+      if (!transcriptFile) return null;
+      return forkOrchestratorSession({
+        orchestratorSessionKey: sessionKey,
+        accountId: opts.accountId,
+        transcriptFile,
+        sessionsDir: opts.sessionsDir,
+      });
+    },
+
+    cleanupFork({ fork }) {
+      if (typeof fork.sessionFile !== "string") return;
+      cleanupForkSession({
+        sessionFile: fork.sessionFile,
+        sessionKey: fork.sessionKey,
+        sessionsDir: opts.sessionsDir,
+      });
+    },
+  };
+}
 
 export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
   startAccount: async (ctx) => {
@@ -259,25 +230,13 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
       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,
@@ -311,496 +270,44 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
       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}`);
+    const dispatchAdapter = createOpenClawDispatchAdapter({
+      core,
+      cfg: ctx.cfg,
+      accountId: ctx.accountId,
+      sessionsDir,
     });
 
-    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)}`);
-          }
-        }
-
+    const gateway = new ParallAgentGateway({
+      accountId: ctx.accountId,
+      client,
+      ws,
+      connectionLabel: wsUrl,
+      config: {
+        parall_url: config.parall_url,
+        api_key: config.api_key,
+        org_id: config.org_id,
+      },
+      agentUserId,
+      runtimeType: "openclaw",
+      runtimeKey: orchestratorKey,
+      runtimeRef: { hostname: os.hostname(), pid: process.pid },
+      dispatchAdapter,
+      log,
+      onConfigUpdate: async () => {
+        await fetchAndApplyPlatformConfig(configManagerOpts);
+      },
+      onSessionReady: async ({ activeSessionId }) => {
         setParallAccountState(ctx.accountId, {
           client,
+          apiUrl: config.parall_url,
+          apiKey: config.api_key,
           orgId: config.org_id,
           agentUserId,
           activeSessionId,
@@ -808,415 +315,20 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
           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)}`);
-      }
+      },
+      onBeforeDisconnect: async () => {
+        stopWikiHelper?.();
+        removeParallAccountState(ctx.accountId);
+      },
     });
 
-    // ── 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();
+    try {
+      await gateway.run(ctx.abortSignal);
+    } finally {
+      if (!ctx.abortSignal.aborted) {
         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();
-      });
-    });
+      }
+    }
   },
 };