@brantrusnak/openclaw-omadeus 1.0.0

package/src/channel.ts

@@ -0,0 +1,817 @@
+import {
+  createTopLevelChannelConfigAdapter,
+} from "openclaw/plugin-sdk/channel-config-helpers";
+import {
+  type ChannelStatusIssue,
+} from "openclaw/plugin-sdk/channel-runtime";
+import { createAttachedChannelResultAdapter } from "openclaw/plugin-sdk/channel-send-result";
+import { buildComputedAccountStatusSnapshot } from "openclaw/plugin-sdk/status-helpers";
+import {
+  buildPassiveChannelStatusSummary,
+  buildTrafficStatusSummary,
+} from "openclaw/plugin-sdk/extension-shared";
+import {
+  DEFAULT_ACCOUNT_ID,
+  missingTargetError,
+  type ChannelPlugin,
+  type OpenClawConfig,
+} from "../runtime-api.js";
+import {
+  ALLOWED_OMADEUS_REACTION_EMOJI_LIST,
+  isAllowedOmadeusReactionEmoji,
+} from "./allowed-reaction-emojis.js";
+import {
+  createNugget,
+  resolveTaskRoomIdByNumber,
+  type OmadeusNuggetKind,
+  type OmadeusNuggetPriority,
+} from "./api/nugget.api.js";
+import { addMessageReaction, deleteMessage, editMessage } from "./api/message.api.js";
+import {
+  listOmadeusAccountIds,
+  resolveDefaultOmadeusAccountId,
+  resolveOmadeusAccount,
+} from "./config.js";
+import { parseJaguarMessage } from "./inbound.js";
+import { createOmadeusMessageHandler } from "./message-handler.js";
+import { parseTaskChannelTargetIntent } from "./nugget-lookup.js";
+import { sendOmadeusMessage, type OutboundDeps } from "./outbound.js";
+import { getOmadeusRuntime } from "./runtime.js";
+import { omadeusSetupAdapter } from "./setup-core.js";
+import { omadeusSetupWizard } from "./setup-surface.js";
+import { createDolphinSocketClient, type DolphinSocketClient } from "./socket/dolphin.socket.js";
+import { createJaguarSocketClient, type JaguarSocketClient } from "./socket/jaguar.socket.js";
+import { createTokenManager, type OmadeusTokenManager } from "./token.js";
+import type { ResolvedOmadeusAccount as Account } from "./types.js";
+
+// Gateway-scoped state for the running account
+let activeTokenManager: OmadeusTokenManager | null = null;
+let activeDolphin: DolphinSocketClient | null = null;
+let activeJaguar: JaguarSocketClient | null = null;
+
+async function persistSessionToken(token: string): Promise<void> {
+  const runtime = getOmadeusRuntime();
+  const cfg = runtime.config.loadConfig();
+  const section = ((cfg.channels as Record<string, unknown> | undefined)?.["omadeus"] ??
+    {}) as Record<string, unknown>;
+  if (section["sessionToken"] === token) {
+    return;
+  }
+
+  await runtime.config.writeConfigFile({
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      omadeus: {
+        ...section,
+        sessionToken: token,
+      },
+    },
+  } as OpenClawConfig);
+}
+
+const omadeusConfigAdapter = createTopLevelChannelConfigAdapter<Account>({
+  sectionKey: "omadeus",
+  resolveAccount: (cfg) => resolveOmadeusAccount({ cfg }),
+  listAccountIds: listOmadeusAccountIds,
+  defaultAccountId: resolveDefaultOmadeusAccountId,
+  deleteMode: "clear-fields",
+  clearBaseFields: [
+    "casUrl",
+    "maestroUrl",
+    "email",
+    "password",
+    "organizationId",
+    "sessionToken",
+    "selectedMemberReferenceId",
+    "selectedChannelViewId",
+    "selectedChannelTitle",
+    "selectedChannelPrivateRoomId",
+    "selectedChannelPublicRoomId",
+  ],
+  // Keep adapter contract satisfied even though Omadeus no longer uses DM allowlists.
+  resolveAllowFrom: () => [],
+  formatAllowFrom: () => [],
+});
+
+const defaultRuntimeState = {
+  accountId: DEFAULT_ACCOUNT_ID,
+  running: false,
+  connected: false,
+  lastConnectedAt: null,
+  lastStartAt: null,
+  lastStopAt: null,
+  lastInboundAt: null,
+  lastOutboundAt: null,
+  lastError: null,
+} as const;
+
+/** Normalize Jaguar chat target: `room:123` or `123` -> `123` (numeric room id for APIs). */
+function normalizeOmadeusRoomId(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const prefixed = /^room:(\d+)$/i.exec(trimmed);
+  if (prefixed) {
+    return prefixed[1];
+  }
+  return /^\d+$/.test(trimmed) ? trimmed : undefined;
+}
+
+function readReactionMessageId(
+  params: Record<string, unknown>,
+  toolContext?: { currentMessageId?: string | number },
+): number | undefined {
+  const raw = params.messageId ?? params.message_id ?? toolContext?.currentMessageId;
+  if (raw == null) {
+    return undefined;
+  }
+  const n = typeof raw === "number" ? raw : Number(String(raw).trim());
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function readStringParam(params: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = params[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+function readNumberParam(params: Record<string, unknown>, keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = params[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "string" && /^\d+$/.test(value.trim())) {
+      return Number(value.trim());
+    }
+  }
+  return undefined;
+}
+
+function readNuggetKind(params: Record<string, unknown>): OmadeusNuggetKind {
+  const raw = readStringParam(params, ["kind", "entity", "type"])?.toLowerCase();
+  return raw === "nugget" ? "nugget" : "task";
+}
+
+function readNuggetPriority(params: Record<string, unknown>): OmadeusNuggetPriority {
+  const raw = readStringParam(params, ["priority"])?.toLowerCase();
+  if (raw === "urgent" || raw === "high" || raw === "medium" || raw === "low") {
+    return raw;
+  }
+  return "low";
+}
+
+function isCreateNuggetRequest(params: Record<string, unknown>): boolean {
+  const op = readStringParam(params, ["op", "operation", "intent"])?.toLowerCase();
+  if (op === "create_nugget" || op === "create_task") {
+    return true;
+  }
+  const create =
+    params["createNugget"] === true ||
+    params["createTask"] === true ||
+    params["create"] === true ||
+    readStringParam(params, ["actionType", "mode"])?.toLowerCase() === "create";
+  if (create) {
+    return true;
+  }
+  return Boolean(readStringParam(params, ["title"]) && readStringParam(params, ["description"]));
+}
+
+export const omadeusPlugin: ChannelPlugin<Account> = {
+  id: "omadeus",
+  meta: {
+    id: "omadeus",
+    label: "Omadeus",
+    selectionLabel: "Omadeus (WebSocket)",
+    docsPath: "/channels/omadeus",
+    docsLabel: "omadeus",
+    blurb: "Omadeus project management — tasks, chat rooms, and sprints.",
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    reactions: true,
+    threads: false,
+    media: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "- Omadeus routing: **send** uses **room id** (`to` / `target`, e.g. `room:117947` or `117947`). **edit**, **delete**, **react** use the Jaguar **message** `id` (`messageId`, or the current inbound message from context).",
+      "- Create Omadeus task/nugget: use `action=send` with params `{ op: \"create_task\"|\"create_nugget\", title, description, priority?, stage?, kind?, memberReferenceId?, clientId?, folderId? }`.",
+      `- Reactions only allow these emojis (others are ignored): ${ALLOWED_OMADEUS_REACTION_EMOJI_LIST.join(" ")}`,
+      "- Reply in chat with plain text; use the message tool for proactive sends, edits, deletes, or reactions.",
+    ],
+  },
+  actions: {
+    describeMessageTool: ({ cfg }) => {
+      const enabled =
+        cfg.channels?.omadeus?.enabled !== false &&
+        resolveOmadeusAccount({ cfg }).credentialSource !== "none";
+      return {
+        actions: enabled ? ["send", "edit", "delete", "react"] : [],
+        capabilities: [],
+        schema: null,
+      };
+    },
+    handleAction: async (ctx) => {
+      const apiOptsForAccount = () => {
+        const account = resolveOmadeusAccount({ cfg: ctx.cfg });
+        if (!activeTokenManager) {
+          throw new Error("Omadeus: not connected; gateway must be running with Omadeus enabled.");
+        }
+        return { maestroUrl: account.maestroUrl, tokenManager: activeTokenManager };
+      };
+
+      if (ctx.action === "send" && isCreateNuggetRequest(ctx.params)) {
+        const title = readStringParam(ctx.params, ["title", "subject", "name"]);
+        const description = readStringParam(ctx.params, ["description", "details", "body"]);
+        if (!title || !description) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus create task/nugget requires `title` and `description`.",
+              },
+            ],
+            details: { error: "Missing title/description." },
+          };
+        }
+
+        const kind = readNuggetKind(ctx.params);
+        const priority = readNuggetPriority(ctx.params);
+        const stage = readStringParam(ctx.params, ["stage"]) ?? "Triage";
+        const memberReferenceId =
+          readNumberParam(ctx.params, ["memberReferenceId", "assigneeReferenceId"]) ??
+          activeTokenManager?.getPayload().referenceId;
+        const clientId = readNumberParam(ctx.params, ["clientId"]) ?? 1;
+        const folderId = readNumberParam(ctx.params, ["folderId"]) ?? 1;
+
+        if (!memberReferenceId) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus create task/nugget needs `memberReferenceId` or an active authenticated user.",
+              },
+            ],
+            details: { error: "Missing memberReferenceId." },
+          };
+        }
+
+        try {
+          const created = await createNugget(apiOptsForAccount(), {
+            title,
+            description,
+            stage,
+            kind,
+            priority,
+            memberReferenceId,
+            clientId,
+            folderId,
+          });
+          const number = created["number"];
+          const id = created["id"];
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  ok: true,
+                  channel: "omadeus",
+                  action: "create",
+                  kind,
+                  number,
+                  id,
+                  title,
+                }),
+              },
+            ],
+            details: {
+              ok: true,
+              channel: "omadeus",
+              action: "create",
+              kind,
+              number,
+              id,
+            },
+          };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            isError: true,
+            content: [{ type: "text" as const, text: msg }],
+            details: { error: msg },
+          };
+        }
+      }
+
+      if (ctx.action === "edit") {
+        const messageId = readReactionMessageId(ctx.params, ctx.toolContext);
+        const body =
+          (typeof ctx.params.message === "string" && ctx.params.message.trim()) ||
+          (typeof ctx.params.text === "string" && ctx.params.text.trim()) ||
+          (typeof ctx.params.content === "string" && ctx.params.content.trim()) ||
+          "";
+        if (messageId == null) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus edit requires `messageId` (Jaguar message id) or current inbound MessageSid.",
+              },
+            ],
+            details: { error: "Missing messageId for edit." },
+          };
+        }
+        if (!body) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus edit requires new text in `message`, `text`, or `content`.",
+              },
+            ],
+            details: { error: "Missing body for edit." },
+          };
+        }
+        try {
+          await editMessage(apiOptsForAccount(), { messageId, body });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            isError: true,
+            content: [{ type: "text" as const, text: msg }],
+            details: { error: msg },
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ ok: true, channel: "omadeus", action: "edit", messageId }),
+            },
+          ],
+          details: { ok: true, channel: "omadeus", messageId },
+        };
+      }
+
+      if (ctx.action === "delete") {
+        const messageId = readReactionMessageId(ctx.params, ctx.toolContext);
+        if (messageId == null) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus delete requires `messageId` (Jaguar message id) or current inbound MessageSid.",
+              },
+            ],
+            details: { error: "Missing messageId for delete." },
+          };
+        }
+        try {
+          await deleteMessage(apiOptsForAccount(), { messageId });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            isError: true,
+            content: [{ type: "text" as const, text: msg }],
+            details: { error: msg },
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ ok: true, channel: "omadeus", action: "delete", messageId }),
+            },
+          ],
+          details: { ok: true, channel: "omadeus", messageId },
+        };
+      }
+
+      if (ctx.action === "react") {
+        const emoji = typeof ctx.params.emoji === "string" ? ctx.params.emoji.trim() : "";
+        if (!emoji) {
+          return {
+            isError: true,
+            content: [{ type: "text" as const, text: "Omadeus react requires `emoji`." }],
+            details: { error: "Omadeus react requires emoji." },
+          };
+        }
+        if (!isAllowedOmadeusReactionEmoji(emoji)) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  ok: true,
+                  channel: "omadeus",
+                  ignored: true,
+                  reason: "unsupported_emoji",
+                  emoji,
+                  allowed: [...ALLOWED_OMADEUS_REACTION_EMOJI_LIST],
+                }),
+              },
+            ],
+            details: {
+              ok: true,
+              ignored: true,
+              channel: "omadeus",
+            },
+          };
+        }
+        const messageId = readReactionMessageId(ctx.params, ctx.toolContext);
+        if (messageId == null) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus react requires `messageId` or a current inbound message id (MessageSid).",
+              },
+            ],
+            details: { error: "Missing messageId for reaction." },
+          };
+        }
+        if (!activeTokenManager) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text" as const,
+                text: "Omadeus is not connected; cannot react (gateway must be running).",
+              },
+            ],
+            details: { error: "Omadeus not connected." },
+          };
+        }
+        try {
+          await addMessageReaction(apiOptsForAccount(), { messageId, emoji });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            isError: true,
+            content: [{ type: "text" as const, text: msg }],
+            details: { error: msg },
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                ok: true,
+                channel: "omadeus",
+                messageId,
+                emoji,
+              }),
+            },
+          ],
+          details: { ok: true, channel: "omadeus", messageId, emoji },
+        };
+      }
+      // Return null to fall through to default handler
+      return null as never;
+    },
+  },
+  reload: { configPrefixes: ["channels.omadeus"] },
+  setup: omadeusSetupAdapter,
+  setupWizard: omadeusSetupWizard,
+
+  // -------------------------------------------------------------------------
+  // Config adapter
+  // -------------------------------------------------------------------------
+  config: {
+    ...omadeusConfigAdapter,
+    isConfigured: (account) => account.credentialSource !== "none",
+    unconfiguredReason: () =>
+      "Omadeus requires email, password, and organizationId. Run: openclaw setup omadeus",
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.credentialSource !== "none",
+      credentialSource: account.credentialSource,
+      baseUrl: account.maestroUrl,
+    }),
+  },
+
+  // Used by shared message-tool target resolution (send, react, etc.).
+  messaging: {
+    targetResolver: {
+      hint: "Use room:<roomId> (matches OpenClaw OriginatingTo) or a numeric Jaguar room id.",
+      looksLikeId: (raw) => {
+        const t = raw.trim();
+        return /^room:\d+$/i.test(t) || /^\d+$/.test(t) || /^[nt]\d+$/i.test(t);
+      },
+      resolveTarget: async ({ cfg, input }) => {
+        const id = normalizeOmadeusRoomId(input);
+        if (!id) {
+          const taskIntent = parseTaskChannelTargetIntent(input);
+          if (!taskIntent || !activeTokenManager) {
+            return null;
+          }
+          const roomId = await resolveTaskRoomIdByNumber(
+            {
+              maestroUrl: resolveOmadeusAccount({ cfg }).maestroUrl,
+              tokenManager: activeTokenManager,
+            },
+            { nuggetNumber: taskIntent.nuggetNumber },
+          );
+          if (!roomId) {
+            return null;
+          }
+          return {
+            to: String(roomId),
+            kind: "group",
+            display: `${taskIntent.rawPrefix.toUpperCase()}${taskIntent.nuggetNumber}`,
+            source: "normalized",
+          };
+        }
+        return {
+          to: id,
+          kind: "group",
+          display: `room:${id}`,
+          source: "normalized",
+        };
+      },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Outbound adapter
+  // -------------------------------------------------------------------------
+  outbound: {
+    deliveryMode: "direct",
+    textChunkLimit: 4000,
+    chunker: (text, limit) => getOmadeusRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    ...createAttachedChannelResultAdapter({
+      channel: "omadeus",
+      sendText: async ({ cfg, to, text }) => {
+        if (!activeJaguar || !activeTokenManager) {
+          throw new Error("Omadeus: not connected. Is the gateway running with Omadeus enabled?");
+        }
+        const deps: OutboundDeps = {
+          apiOpts: {
+            maestroUrl: resolveOmadeusAccount({
+              cfg,
+            }).maestroUrl,
+            tokenManager: activeTokenManager,
+          },
+          jaguarSocket: activeJaguar,
+        };
+        return await sendOmadeusMessage(deps, { to, text });
+      },
+    }),
+    resolveTarget: ({ to }) => {
+      const trimmed = to?.trim() ?? "";
+      const id = normalizeOmadeusRoomId(trimmed);
+      if (!id) {
+        if (/^[nt]\d+$/i.test(trimmed)) {
+          // Allow task-id-like target to proceed; async target resolver may dock it to a room later.
+          return { ok: true, to: trimmed };
+        }
+        return {
+          ok: false,
+          error: missingTargetError("Omadeus", "room:<roomId> or numeric room id"),
+        };
+      }
+      return { ok: true, to: id };
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Status adapter
+  // -------------------------------------------------------------------------
+  status: {
+    defaultRuntime: defaultRuntimeState,
+    collectStatusIssues: (accounts): ChannelStatusIssue[] =>
+      accounts.flatMap((entry) => {
+        const issues: ChannelStatusIssue[] = [];
+        if (entry.enabled !== false && entry.configured !== true) {
+          issues.push({
+            channel: "omadeus",
+            accountId: String(entry.accountId ?? DEFAULT_ACCOUNT_ID),
+            kind: "config",
+            message: "Omadeus credentials are missing.",
+            fix: "Run: openclaw setup omadeus",
+          });
+        }
+        return issues;
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      ...buildPassiveChannelStatusSummary(snapshot, {
+        credentialSource: snapshot.credentialSource ?? "none",
+        baseUrl: snapshot.baseUrl ?? null,
+        connected: snapshot.connected ?? false,
+        lastConnectedAt: snapshot.lastConnectedAt ?? null,
+      }),
+      ...buildTrafficStatusSummary(snapshot),
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      ...buildComputedAccountStatusSnapshot({
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: account.credentialSource !== "none",
+        runtime,
+      }),
+      baseUrl: account.maestroUrl,
+      credentialSource: account.credentialSource,
+      connected: runtime?.connected ?? false,
+      lastConnectedAt: runtime?.lastConnectedAt ?? null,
+    }),
+  },
+
+  // -------------------------------------------------------------------------
+  // Gateway adapter — starts sockets on gateway boot
+  // -------------------------------------------------------------------------
+  gateway: {
+    startAccount: async (ctx) => {
+      const { account, cfg, abortSignal } = ctx;
+      ctx.log?.info(`[omadeus] starting for org ${account.organizationId}`);
+
+      if (account.credentialSource === "none") {
+        ctx.log?.warn("[omadeus] skipping start: credentials not configured");
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          lastError: "credentials not configured",
+        });
+        return;
+      }
+
+      const hasCachedSession = Boolean(account.sessionToken?.trim());
+      if (!account.password && !hasCachedSession) {
+        ctx.log?.warn("[omadeus] skipping start: password/sessionToken not set");
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          lastError: "password/sessionToken not set",
+        });
+        return;
+      }
+
+      const log = ctx.log ?? { info: () => {}, warn: () => {}, error: () => {} };
+
+      // Auth
+      const tokenManager = createTokenManager({
+        casUrl: account.casUrl,
+        maestroUrl: account.maestroUrl,
+        email: account.email,
+        password: account.password,
+        organizationId: account.organizationId,
+        initialToken: account.sessionToken,
+        onRefresh: (token) => {
+          log.info("[omadeus] token refreshed");
+          void persistSessionToken(token).catch((err) =>
+            log.warn(`[omadeus] failed to persist session token: ${String(err)}`),
+          );
+        },
+        onError: (err) => {
+          log.error(`[omadeus] token refresh failed: ${err.message}`);
+          ctx.setStatus({ accountId: account.accountId, lastError: err.message });
+        },
+      });
+
+      try {
+        await tokenManager.refresh();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`[omadeus] initial auth failed: ${msg}`);
+        ctx.setStatus({ accountId: account.accountId, running: false, lastError: msg });
+        return;
+      }
+
+      tokenManager.startAutoRefresh();
+      activeTokenManager = tokenManager;
+
+      const selfReferenceId = tokenManager.getPayload().referenceId;
+
+      const outboundDeps: OutboundDeps = {
+        apiOpts: { maestroUrl: account.maestroUrl, tokenManager },
+        jaguarSocket: null as unknown as JaguarSocketClient,
+      };
+
+      const handleMessage = createOmadeusMessageHandler({
+        cfg,
+        runtime: ctx.runtime,
+        log,
+        outboundDeps,
+      });
+
+      // Jaguar socket (chat — DMs, nugget/task/project rooms)
+      const jaguar = createJaguarSocketClient({
+        maestroUrl: account.maestroUrl,
+        tokenManager,
+        log,
+        onMessage: (msg) => {
+          const label =
+            msg.subscribableKind === "direct"
+              ? `DM from ${msg.senderReferenceId}`
+              : `${msg.subscribableKind}/${msg.roomName ?? msg.roomId} from ${msg.senderReferenceId}`;
+          log.info(`[jaguar] ${label}: ${msg.body.slice(0, 80)}`);
+
+          const inbound = parseJaguarMessage(msg, { selfReferenceId }, log);
+          if (inbound) {
+            log.info(
+              `[jaguar] inbound: ${inbound.subscribableKind} room=${inbound.roomId} ` +
+                `from=${inbound.from} mention=${inbound.isMention}`,
+            );
+            ctx.setStatus({ accountId: account.accountId, lastInboundAt: Date.now() });
+            handleMessage(inbound).catch((err) => {
+              log.error(
+                `[jaguar] dispatch error: ${err instanceof Error ? err.message : String(err)}`,
+              );
+            });
+          }
+        },
+        onOtherEvent: (data) => {
+          log.info(`[jaguar] non-message event: ${JSON.stringify(data).slice(0, 120)}`);
+        },
+        onConnect: () =>
+          ctx.setStatus({
+            accountId: account.accountId,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          }),
+        onDisconnect: () => ctx.setStatus({ accountId: account.accountId, connected: false }),
+        onError: (err) => ctx.setStatus({ accountId: account.accountId, lastError: err.message }),
+      });
+
+      // Dolphin socket (data — tasks, projects, sprints, releases)
+      const dolphin = createDolphinSocketClient({
+        maestroUrl: account.maestroUrl,
+        tokenManager,
+        log,
+        onEvent: (data) => {
+          log.info(`[dolphin] event: ${JSON.stringify(data).slice(0, 120)}`);
+          // TODO: handle task assignment/update events as they are discovered
+        },
+        onConnect: () =>
+          ctx.setStatus({
+            accountId: account.accountId,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          }),
+        onDisconnect: () => ctx.setStatus({ accountId: account.accountId, connected: false }),
+        onError: (err) => ctx.setStatus({ accountId: account.accountId, lastError: err.message }),
+      });
+
+      // Wire the jaguar socket into outbound deps now that it's created
+      outboundDeps.jaguarSocket = jaguar;
+
+      jaguar.connect();
+      dolphin.connect();
+      activeJaguar = jaguar;
+      activeDolphin = dolphin;
+
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        lastStartAt: Date.now(),
+      });
+
+      let cleanedUp = false;
+      const cleanup = () => {
+        if (cleanedUp) return;
+        cleanedUp = true;
+        tokenManager.stopAutoRefresh();
+        jaguar.disconnect();
+        dolphin.disconnect();
+        activeTokenManager = null;
+        activeJaguar = null;
+        activeDolphin = null;
+        ctx.setStatus({
+          accountId: account.accountId,
+          running: false,
+          lastStopAt: Date.now(),
+        });
+      };
+
+      // Keep this account runner alive until the gateway aborts it.
+      await new Promise<void>((resolve) => {
+        if (abortSignal.aborted) {
+          resolve();
+          return;
+        }
+        abortSignal.addEventListener("abort", () => resolve(), { once: true });
+      });
+
+      cleanup();
+    },
+  },
+};