@hywkp/test-openclaw-sider 1.0.2

package/src/channel.ts

@@ -0,0 +1,3864 @@
+import {
+  type ChannelPlugin,
+  type OpenClawConfig,
+  type PluginRuntime,
+  type ReplyPayload,
+} from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { jsonResult, readStringParam } from "openclaw/plugin-sdk/agent-runtime";
+import {
+  createChannelReplyPipeline,
+  type CreateTypingCallbacksParams,
+} from "openclaw/plugin-sdk/channel-reply-pipeline";
+import { loadConfig, writeConfigFile } from "openclaw/plugin-sdk/config-runtime";
+import {
+  getAgentScopedMediaLocalRoots,
+  resolveChannelMediaMaxBytes,
+} from "openclaw/plugin-sdk/media-runtime";
+import {
+  formatTextWithAttachmentLinks,
+  resolveOutboundMediaUrls,
+} from "openclaw/plugin-sdk/reply-payload";
+
+type ChannelMeta = ChannelPlugin["meta"];
+import { appendTokenQuery } from "./auth.js";
+import {
+  describeSiderAccountConfigurationError,
+  extractSiderToolSend,
+  isSiderAccountBootstrappable,
+  listSiderAccountIds,
+  looksLikeSiderTargetId,
+  normalizeSiderMessagingTarget,
+  resolveManagedSiderAccount,
+  resolveOutboundSessionId,
+  resolveSiderAccount,
+  type ResolvedSiderAccount,
+  siderSetupWizard,
+} from "./account.js";
+import {
+  SIDER_CHANNEL_ALIASES,
+  SIDER_CHANNEL_BLURB,
+  SIDER_CHANNEL_DOCS_LABEL,
+  SIDER_CHANNEL_DOCS_PATH,
+  SIDER_CHANNEL_ID,
+  SIDER_CHANNEL_LABEL,
+  SIDER_CHANNEL_SELECTION_LABEL,
+} from "./config.js";
+import { resolveInboundSiderMedia } from "./inbound-media.js";
+import { buildSiderPartFromInlineAttachment, buildSiderPartsFromReplyPayload } from "./media-upload.js";
+import {
+  applySiderSetupAccountConfig,
+  createSiderPairingPendingUpdateReporter,
+  formatSiderPairingInstructions,
+  requestSiderPairing,
+  SiderPairingExpiredError,
+  siderSetupAdapter,
+  waitForSiderPairing,
+} from "./setup-core.js";
+import { SIDER_PLUGIN_VERSION, SIDER_USER_AGENT } from "./user-agent.js";
+const DEFAULT_MEDIA_SAVE_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MONITOR_KEEPALIVE_MS = 10_000;
+const DEFAULT_MONITOR_PONG_TIMEOUT_MS = 30_000;
+const DEFAULT_STRUCTURED_PAYLOAD_MAX_CHARS = 12_000;
+
+type SiderPart = {
+  id?: string;
+  type: string;
+  spec_version?: number;
+  payload?: unknown;
+  meta?: unknown;
+};
+
+type SiderInboundAck = {
+  type: "ack";
+  session_id?: string;
+  id?: string;
+  client_req_id?: string;
+};
+
+type SiderInboundRealtimeMessage = {
+  type: "message";
+  session_id?: string;
+  message_id?: string;
+  source_role?: string;
+  created_at?: number;
+  parts?: SiderPart[];
+  meta?: unknown;
+};
+
+type SiderInboundRealtimeEvent = {
+  type: "event";
+  session_id?: string;
+  event_id?: string;
+  event_type?: string;
+  source_role?: string;
+  created_at?: number;
+  payload?: unknown;
+  meta?: unknown;
+};
+
+type SiderSampleEvent = {
+  eventType: string;
+  payload: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+};
+
+type SiderUsageTotals = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  total?: number;
+};
+
+type SiderParsedToolCall = {
+  toolName?: string;
+  toolCallId?: string;
+  toolArgs?: unknown;
+};
+
+type SiderParsedAssistantOutput = {
+  stopReason?: string;
+  thinkingText?: string;
+  toolCalls: SiderParsedToolCall[];
+};
+
+type SiderRunState = {
+  runId: string;
+  sessionKey?: string;
+  sessionId?: string;
+  accountId?: string;
+  provider?: string;
+  model?: string;
+  usage: SiderUsageTotals;
+  pendingStructuredParts: SiderPart[];
+  pendingFinalThinking?: string;
+  pendingFinalStopReason?: string;
+  updatedAt: number;
+};
+
+type SiderStreamState = {
+  active: boolean;
+  streamId?: string;
+  seq: number;
+  blockDeltaCount: number;
+  partialDeltaCount: number;
+  streamDeltaMode: "undecided" | "partial" | "block";
+  partialSnapshot: string;
+  accumulatedBlockText: string;
+  persistedFinalText: boolean;
+  pendingFinalPayload?: ReplyPayload;
+  sessionKey?: string;
+  currentRunId?: string;
+  streamEventQueue: Promise<void>;
+};
+
+type SiderSessionBinding = {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  lastSeenAt: number;
+  toolSeq: number;
+  currentRunId?: string;
+  currentToolCallId?: string;
+  callIdByToolCallId: Map<string, string>;
+};
+
+type SiderToolHookPayload = {
+  sessionKey?: string;
+  phase: "start" | "end" | "error";
+  toolName?: string;
+  toolCallId?: string;
+  runId?: string;
+  params?: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+  durationMs?: number;
+};
+
+type SiderInboundReplaced = {
+  type: "replaced";
+  reason?: string;
+};
+
+type SiderInboundPing = {
+  type: "ping";
+};
+
+type SiderInboundPong = {
+  type: "pong";
+};
+
+type SiderInboundFrame =
+  | SiderInboundAck
+  | SiderInboundRealtimeMessage
+  | SiderInboundRealtimeEvent
+  | SiderInboundReplaced
+  | SiderInboundPing
+  | SiderInboundPong
+
+type SiderPendingAck = {
+  sessionId: string;
+  clientReqId?: string;
+  timeout: ReturnType<typeof setTimeout>;
+  resolve: (id: string) => void;
+  reject: (err: Error) => void;
+};
+
+type SiderRelaySocketReadyWaiter = {
+  timeout: ReturnType<typeof setTimeout>;
+  resolve: (ws: WebSocket) => void;
+  reject: (err: Error) => void;
+};
+
+type SiderNodeWebSocketCtor = new (
+  url: string,
+  options?: {
+    headers?: Record<string, string>;
+    protocols?: string | string[];
+  },
+) => WebSocket;
+
+const SiderNodeWebSocket = WebSocket as unknown as SiderNodeWebSocketCtor;
+
+function createSiderWebSocket(url: string): WebSocket {
+  return new SiderNodeWebSocket(url, {
+    headers: {
+      "User-Agent": SIDER_USER_AGENT,
+    },
+  });
+}
+
+type SiderRelaySocketState = {
+  ws: WebSocket | null;
+  accountSignature?: string;
+  relayId?: string;
+  filteredSubscription: boolean;
+  subscribedSessionIds: Set<string>;
+  pendingAcksBySession: Map<string, SiderPendingAck[]>;
+  pendingAcksByClientReqId: Map<string, SiderPendingAck>;
+  readyWaiters: Set<SiderRelaySocketReadyWaiter>;
+};
+
+type SiderMonitorLogger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+type SiderRelayMonitorRegistration = {
+  cfg: OpenClawConfig;
+  account: ResolvedSiderAccount;
+  monitorSignature: string;
+  subscribers: Set<string>;
+  controller: AbortController;
+  runner: Promise<void>;
+  restartRequested: boolean;
+  log?: SiderMonitorLogger;
+};
+
+type ParsedInboundMedia = {
+  url?: string;
+  mimeType?: string;
+  fileName?: string;
+  objectKey?: string;
+  fileId?: string;
+};
+
+const meta: ChannelMeta = {
+  id: SIDER_CHANNEL_ID,
+  label: SIDER_CHANNEL_LABEL,
+  selectionLabel: SIDER_CHANNEL_SELECTION_LABEL,
+  docsPath: SIDER_CHANNEL_DOCS_PATH,
+  docsLabel: SIDER_CHANNEL_DOCS_LABEL,
+  blurb: SIDER_CHANNEL_BLURB,
+  aliases: [...SIDER_CHANNEL_ALIASES],
+  order: 97,
+};
+
+let runtimeRef: PluginRuntime | null = null;
+const SIDER_SESSION_BINDING_TTL_MS = 6 * 60 * 60 * 1000;
+const SIDER_SESSION_BINDING_MAX = 512;
+const siderSessionBindings = new Map<string, SiderSessionBinding>();
+const SIDER_RUN_STATE_TTL_MS = 6 * 60 * 60 * 1000;
+const SIDER_RUN_STATE_MAX = 1024;
+const siderRunStates = new Map<string, SiderRunState>();
+const siderRelaySockets = new Map<string, SiderRelaySocketState>();
+const siderRelayMonitors = new Map<string, SiderRelayMonitorRegistration>();
+
+export function setSiderRuntime(runtime: PluginRuntime): void {
+  runtimeRef = runtime;
+}
+
+function getSiderRuntime(): PluginRuntime {
+  if (!runtimeRef) {
+    throw new Error("sider runtime not initialized");
+  }
+  return runtimeRef;
+}
+
+function formatLogMessage(message: string, data?: Record<string, unknown>): string {
+  if (!data || Object.keys(data).length === 0) {
+    return message;
+  }
+  try {
+    return `${message} ${JSON.stringify(data)}`;
+  } catch {
+    return message;
+  }
+}
+
+function logDebug(message: string, data?: Record<string, unknown>): void {
+  const core = getSiderRuntime();
+  if (!core.logging.shouldLogVerbose()) {
+    return;
+  }
+  core.logging.getChildLogger({ channel: SIDER_CHANNEL_ID }).debug?.(formatLogMessage(message, data));
+}
+
+function logInfo(message: string, data?: Record<string, unknown>): void {
+  getSiderRuntime()
+    .logging.getChildLogger({ channel: SIDER_CHANNEL_ID })
+    .info(formatLogMessage(message, data));
+}
+
+function logWarn(message: string, data?: Record<string, unknown>): void {
+  getSiderRuntime()
+    .logging.getChildLogger({ channel: SIDER_CHANNEL_ID })
+    .warn(formatLogMessage(message, data));
+}
+
+function createMonitorLogger(log?: SiderMonitorLogger): {
+  info: (message: string, data?: Record<string, unknown>) => void;
+  warn: (message: string, data?: Record<string, unknown>) => void;
+} {
+  const emit = (level: "info" | "warn", message: string, data?: Record<string, unknown>) => {
+    if (log) {
+      log[level](formatLogMessage(message, data));
+      return;
+    }
+    if (level === "info") {
+      logInfo(message, data);
+      return;
+    }
+    logWarn(message, data);
+  };
+
+  return {
+    info: (message, data) => emit("info", message, data),
+    warn: (message, data) => emit("warn", message, data),
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeSessionBindingKey(raw?: string): string | undefined {
+  const key = raw?.trim().toLowerCase();
+  return key || undefined;
+}
+
+function pruneSiderSessionBindings(now = Date.now()): void {
+  for (const [key, binding] of siderSessionBindings) {
+    if (now - binding.lastSeenAt > SIDER_SESSION_BINDING_TTL_MS) {
+      siderSessionBindings.delete(key);
+    }
+  }
+  if (siderSessionBindings.size <= SIDER_SESSION_BINDING_MAX) {
+    return;
+  }
+  const sorted = [...siderSessionBindings.entries()].sort(
+    (a, b) => a[1].lastSeenAt - b[1].lastSeenAt,
+  );
+  const overflow = siderSessionBindings.size - SIDER_SESSION_BINDING_MAX;
+  for (let index = 0; index < overflow; index += 1) {
+    const key = sorted[index]?.[0];
+    if (key) {
+      siderSessionBindings.delete(key);
+    }
+  }
+}
+
+function rememberSiderSessionBinding(params: {
+  sessionKey?: string;
+  account: ResolvedSiderAccount;
+  sessionId: string;
+}): void {
+  const key = normalizeSessionBindingKey(params.sessionKey);
+  if (!key) {
+    return;
+  }
+  const now = Date.now();
+  const existing = siderSessionBindings.get(key);
+  if (existing) {
+    existing.account = params.account;
+    existing.sessionId = params.sessionId;
+    existing.lastSeenAt = now;
+    pruneSiderSessionBindings(now);
+    return;
+  }
+  siderSessionBindings.set(key, {
+    account: params.account,
+    sessionId: params.sessionId,
+    lastSeenAt: now,
+    toolSeq: 0,
+    currentRunId: undefined,
+    currentToolCallId: undefined,
+    callIdByToolCallId: new Map(),
+  });
+  pruneSiderSessionBindings(now);
+}
+
+function resolveSiderSessionBinding(sessionKey?: string): SiderSessionBinding | undefined {
+  const key = normalizeSessionBindingKey(sessionKey);
+  if (!key) {
+    return undefined;
+  }
+  const binding = siderSessionBindings.get(key);
+  if (!binding) {
+    return undefined;
+  }
+  binding.lastSeenAt = Date.now();
+  return binding;
+}
+
+function pruneSiderRunStates(now = Date.now()): void {
+  for (const [runId, state] of siderRunStates) {
+    if (now - state.updatedAt > SIDER_RUN_STATE_TTL_MS) {
+      siderRunStates.delete(runId);
+    }
+  }
+  if (siderRunStates.size <= SIDER_RUN_STATE_MAX) {
+    return;
+  }
+  const sorted = [...siderRunStates.entries()].sort((a, b) => a[1].updatedAt - b[1].updatedAt);
+  const overflow = siderRunStates.size - SIDER_RUN_STATE_MAX;
+  for (let index = 0; index < overflow; index += 1) {
+    const runId = sorted[index]?.[0];
+    if (runId) {
+      siderRunStates.delete(runId);
+    }
+  }
+}
+
+function getOrCreateSiderRunState(runId: string): SiderRunState {
+  const now = Date.now();
+  const existing = siderRunStates.get(runId);
+  if (existing) {
+    existing.updatedAt = now;
+    pruneSiderRunStates(now);
+    return existing;
+  }
+  const created: SiderRunState = {
+    runId,
+    usage: {},
+    pendingStructuredParts: [],
+    updatedAt: now,
+  };
+  siderRunStates.set(runId, created);
+  pruneSiderRunStates(now);
+  return created;
+}
+
+function resolveSiderRunState(runId?: string): SiderRunState | undefined {
+  if (!runId) {
+    return undefined;
+  }
+  const state = siderRunStates.get(runId);
+  if (!state) {
+    return undefined;
+  }
+  state.updatedAt = Date.now();
+  return state;
+}
+
+function discardSiderRunState(runId?: string): void {
+  if (!runId) {
+    return;
+  }
+  siderRunStates.delete(runId);
+}
+
+function hasFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function hasFinitePositiveNumber(value: unknown): value is number {
+  return hasFiniteNumber(value) && value > 0;
+}
+
+function addUsageTotals(target: SiderUsageTotals, next?: SiderUsageTotals): void {
+  if (!next) {
+    return;
+  }
+  const fields: Array<keyof SiderUsageTotals> = [
+    "input",
+    "output",
+    "cacheRead",
+    "cacheWrite",
+    "total",
+  ];
+  for (const field of fields) {
+    const value = next[field];
+    if (!hasFiniteNumber(value)) {
+      continue;
+    }
+    target[field] = hasFiniteNumber(target[field]) ? (target[field] as number) + value : value;
+  }
+}
+
+function hasUsageTotals(usage?: SiderUsageTotals): boolean {
+  if (!usage) {
+    return false;
+  }
+  return (
+    hasFiniteNumber(usage.input) ||
+    hasFiniteNumber(usage.output) ||
+    hasFiniteNumber(usage.cacheRead) ||
+    hasFiniteNumber(usage.cacheWrite) ||
+    hasFiniteNumber(usage.total)
+  );
+}
+
+function hasNonZeroUsageTotals(usage?: SiderUsageTotals): boolean {
+  if (!usage) {
+    return false;
+  }
+  return (
+    hasFinitePositiveNumber(usage.input) ||
+    hasFinitePositiveNumber(usage.output) ||
+    hasFinitePositiveNumber(usage.cacheRead) ||
+    hasFinitePositiveNumber(usage.cacheWrite) ||
+    hasFinitePositiveNumber(usage.total)
+  );
+}
+
+function toUsageCount(value: unknown): number | undefined {
+  if (hasFiniteNumber(value)) {
+    return value < 0 ? 0 : value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) {
+      return undefined;
+    }
+    return parsed < 0 ? 0 : parsed;
+  }
+  return undefined;
+}
+
+function firstUsageCount(...values: unknown[]): number | undefined {
+  let fallback: number | undefined;
+  for (const value of values) {
+    const normalized = toUsageCount(value);
+    if (!hasFiniteNumber(normalized)) {
+      continue;
+    }
+    if (normalized > 0) {
+      return normalized;
+    }
+    if (!hasFiniteNumber(fallback)) {
+      fallback = normalized;
+    }
+  }
+  return fallback;
+}
+
+function toJsonSafeValue(value: unknown): unknown {
+  if (value === undefined) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+}
+
+function clipText(text: string, maxChars = DEFAULT_STRUCTURED_PAYLOAD_MAX_CHARS): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return `${text.slice(0, maxChars)}...`;
+}
+
+function appendStructuredPayloadField(
+  payload: Record<string, unknown>,
+  fieldName: string,
+  value: unknown,
+  maxChars = DEFAULT_STRUCTURED_PAYLOAD_MAX_CHARS,
+): void {
+  const safeValue = toJsonSafeValue(value);
+  if (safeValue === undefined) {
+    return;
+  }
+  let serialized = "";
+  try {
+    serialized = JSON.stringify(safeValue);
+  } catch {
+    serialized = String(safeValue);
+  }
+  if (!serialized) {
+    return;
+  }
+  if (serialized.length <= maxChars) {
+    payload[fieldName] = safeValue;
+    return;
+  }
+  payload[`${fieldName}_preview`] = clipText(serialized, maxChars);
+  payload[`${fieldName}_truncated`] = true;
+}
+
+function extractToolResultText(result: unknown): string {
+  const record = toRecord(result);
+  if (!record) {
+    return "";
+  }
+  const candidateKeys = ["text", "content", "message", "output", "stdout"] as const;
+  for (const key of candidateKeys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      return clipText(value.trim(), 4000);
+    }
+  }
+  return "";
+}
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function getSocketCloseInfo(event?: Event): { code?: number; reason?: string; wasClean?: boolean } {
+  if (!event || typeof event !== "object") {
+    return {};
+  }
+  const candidate = event as Partial<CloseEvent>;
+  return {
+    code: typeof candidate.code === "number" ? candidate.code : undefined,
+    reason: typeof candidate.reason === "string" ? candidate.reason : undefined,
+    wasClean: typeof candidate.wasClean === "boolean" ? candidate.wasClean : undefined,
+  };
+}
+
+function describeSocketClose(event?: Event): string {
+  const { code, reason, wasClean } = getSocketCloseInfo(event);
+  const parts: string[] = [];
+  if (typeof code === "number") {
+    parts.push(`code=${code}`);
+  }
+  if (typeof reason === "string" && reason) {
+    parts.push(`reason=${reason}`);
+  }
+  if (typeof wasClean === "boolean") {
+    parts.push(`clean=${wasClean}`);
+  }
+  return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
+function decodeBase64AttachmentBuffer(raw: string): Buffer {
+  const normalized = raw.trim();
+  if (!normalized) {
+    throw new Error("sider sendAttachment requires non-empty buffer");
+  }
+  const buffer = Buffer.from(normalized, "base64");
+  if (buffer.length === 0) {
+    throw new Error("sider sendAttachment requires valid non-empty base64 buffer");
+  }
+  return buffer;
+}
+
+async function persistInlineAttachmentBuffer(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+}): Promise<{ path: string; contentType?: string }> {
+  const configuredMaxBytes = resolveChannelMediaMaxBytes({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    resolveChannelLimitMb: () => undefined,
+  });
+  const maxBytes = Math.max(
+    params.buffer.length,
+    configuredMaxBytes ?? 0,
+    DEFAULT_MEDIA_SAVE_MAX_BYTES,
+  );
+  return await getSiderRuntime().channel.media.saveMediaBuffer(
+    params.buffer,
+    params.contentType,
+    "outbound",
+    maxBytes,
+    params.fileName,
+  );
+}
+
+function resolveRelayWsUrl(gatewayUrl: string): string {
+  const url = new URL(gatewayUrl);
+  if (url.pathname === "" || url.pathname === "/") {
+    url.pathname = "/ws/relay";
+  } else if (!url.pathname.endsWith("/ws/relay")) {
+    url.pathname = `${url.pathname.replace(/\/+$/, "")}/ws/relay`;
+  }
+  if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  } else if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  } else if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+    throw new Error(`Unsupported gateway URL protocol: ${url.protocol}`);
+  }
+  return url.toString();
+}
+
+async function wsDataToText(data: unknown): Promise<string> {
+  if (typeof data === "string") {
+    return data;
+  }
+  if (data instanceof ArrayBuffer) {
+    return new TextDecoder().decode(data);
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new TextDecoder().decode(data);
+  }
+  if (typeof Blob !== "undefined" && data instanceof Blob) {
+    return await data.text();
+  }
+  return String(data ?? "");
+}
+
+function parseInboundFrame(rawText: string): SiderInboundFrame | null {
+  try {
+    const parsed = JSON.parse(rawText) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    if (typeof parsed.type !== "string" || !parsed.type.trim()) {
+      return null;
+    }
+    return parsed as unknown as SiderInboundFrame;
+  } catch {
+    return null;
+  }
+}
+
+async function waitForSocketOpen(params: {
+  ws: WebSocket;
+  timeoutMs: number;
+  accountId: string;
+}): Promise<void> {
+  const { ws, timeoutMs, accountId } = params;
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(new Error(`[${accountId}] websocket open timeout (${timeoutMs}ms)`));
+    }, timeoutMs);
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      ws.removeEventListener("open", onOpen);
+      ws.removeEventListener("close", onClose);
+      ws.removeEventListener("error", onError);
+    };
+
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onClose = (event: Event) => {
+      cleanup();
+      reject(new Error(`[${accountId}] websocket closed before open${describeSocketClose(event)}`));
+    };
+    const onError = () => {
+      cleanup();
+      reject(new Error(`[${accountId}] websocket failed before open`));
+    };
+
+    ws.addEventListener("open", onOpen);
+    ws.addEventListener("close", onClose);
+    ws.addEventListener("error", onError);
+  });
+}
+
+function closeSocketQuietly(ws: WebSocket): void {
+  try {
+    ws.close();
+  } catch {
+    // no-op
+  }
+}
+
+function normalizeRelaySocketToken(token?: string): string | undefined {
+  const trimmed = token?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function getOrCreateRelaySocketState(accountId: string): SiderRelaySocketState {
+  const existing = siderRelaySockets.get(accountId);
+  if (existing) {
+    return existing;
+  }
+  const next: SiderRelaySocketState = {
+    ws: null,
+    accountSignature: undefined,
+    relayId: undefined,
+    filteredSubscription: false,
+    subscribedSessionIds: new Set<string>(),
+    pendingAcksBySession: new Map<string, SiderPendingAck[]>(),
+    pendingAcksByClientReqId: new Map<string, SiderPendingAck>(),
+    readyWaiters: new Set<SiderRelaySocketReadyWaiter>(),
+  };
+  siderRelaySockets.set(accountId, next);
+  return next;
+}
+
+function buildRelaySocketAccountSignature(account: ResolvedSiderAccount): string {
+  return `${account.gatewayUrl}|${account.relayId}|${normalizeRelaySocketToken(account.token) ?? ""}`;
+}
+
+function buildRelayMonitorAccountSignature(account: ResolvedSiderAccount): string {
+  const subscribeSessionKey = Array.from(
+    new Set((account.subscribeSessionIds ?? []).map((item) => item.trim()).filter(Boolean)),
+  )
+    .sort()
+    .join(",");
+  return [
+    buildRelaySocketAccountSignature(account),
+    subscribeSessionKey,
+    String(account.connectTimeoutMs),
+    String(account.reconnectDelayMs),
+  ].join("|");
+}
+
+function waitForAbortSignal(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function clearRelaySocketState(params: {
+  accountId: string;
+  expectedWs?: WebSocket;
+  closeSocket?: boolean;
+  reason?: string;
+}): void {
+  const state = siderRelaySockets.get(params.accountId);
+  if (!state) {
+    return;
+  }
+  if (params.expectedWs && state.ws && state.ws !== params.expectedWs) {
+    return;
+  }
+  if (params.closeSocket && state.ws && state.ws.readyState !== WebSocket.CLOSED) {
+    closeSocketQuietly(state.ws);
+  }
+  state.ws = null;
+  state.relayId = undefined;
+  state.accountSignature = undefined;
+  state.filteredSubscription = false;
+  state.subscribedSessionIds.clear();
+  const ackError = new Error(
+    params.reason ? `[${params.accountId}] ${params.reason}` : `[${params.accountId}] relay socket closed`,
+  );
+  const rejected = new Set<SiderPendingAck>();
+  for (const pendingAcks of state.pendingAcksBySession.values()) {
+    for (const pendingAck of pendingAcks) {
+      if (rejected.has(pendingAck)) {
+        continue;
+      }
+      rejected.add(pendingAck);
+      clearTimeout(pendingAck.timeout);
+      pendingAck.reject(ackError);
+    }
+  }
+  state.pendingAcksBySession.clear();
+  state.pendingAcksByClientReqId.clear();
+}
+
+function setRelaySocketConnected(params: {
+  account: ResolvedSiderAccount;
+  ws: WebSocket;
+  relayId: string;
+  subscribeSessionIds?: string[];
+}): void {
+  const state = getOrCreateRelaySocketState(params.account.accountId);
+  const nextSubscribedSessionIds = new Set(
+    (params.subscribeSessionIds ?? []).map((sessionId) => sessionId.trim()).filter(Boolean),
+  );
+  state.ws = params.ws;
+  state.relayId = params.relayId;
+  state.accountSignature = buildRelaySocketAccountSignature(params.account);
+  state.filteredSubscription = nextSubscribedSessionIds.size > 0;
+  state.subscribedSessionIds = nextSubscribedSessionIds;
+  for (const waiter of state.readyWaiters) {
+    clearTimeout(waiter.timeout);
+    waiter.resolve(params.ws);
+  }
+  state.readyWaiters.clear();
+}
+
+async function waitForRelaySocketReady(params: {
+  account: ResolvedSiderAccount;
+  timeoutMs: number;
+}): Promise<{ ws: WebSocket; state: SiderRelaySocketState }> {
+  const state = getOrCreateRelaySocketState(params.account.accountId);
+  const expectedSignature = buildRelaySocketAccountSignature(params.account);
+  const liveSocket = state.ws;
+  if (
+    liveSocket &&
+    liveSocket.readyState === WebSocket.OPEN &&
+    state.accountSignature === expectedSignature
+  ) {
+    return { ws: liveSocket, state };
+  }
+  if (liveSocket && state.accountSignature !== expectedSignature) {
+    closeSocketQuietly(liveSocket);
+    clearRelaySocketState({
+      accountId: params.account.accountId,
+      expectedWs: liveSocket,
+      closeSocket: false,
+      reason: "relay socket account settings changed",
+    });
+  }
+  const ws = await new Promise<WebSocket>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      state.readyWaiters.delete(waiter);
+      reject(new Error(`[${params.account.accountId}] timeout waiting managed relay socket`));
+    }, params.timeoutMs);
+    const waiter: SiderRelaySocketReadyWaiter = {
+      timeout,
+      resolve,
+      reject,
+    };
+    state.readyWaiters.add(waiter);
+  });
+  if (state.accountSignature !== expectedSignature) {
+    throw new Error(`[${params.account.accountId}] managed relay socket account signature mismatch`);
+  }
+  return { ws, state };
+}
+
+function ensureRelaySocketSessionSubscription(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  ws: WebSocket;
+  state: SiderRelaySocketState;
+}): void {
+  if (!params.state.filteredSubscription || params.state.subscribedSessionIds.has(params.sessionId)) {
+    return;
+  }
+  if (params.ws.readyState !== WebSocket.OPEN) {
+    throw new Error(`[${params.account.accountId}] managed relay socket is not open`);
+  }
+  params.ws.send(
+    JSON.stringify({
+      type: "subscribe",
+      session_ids: [params.sessionId],
+    }),
+  );
+  params.state.subscribedSessionIds.add(params.sessionId);
+}
+
+function waitForManagedAck(params: {
+  state: SiderRelaySocketState;
+  accountId: string;
+  sessionId: string;
+  timeoutMs: number;
+  clientReqId?: string;
+}): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const pendingAck: SiderPendingAck = {
+      sessionId: params.sessionId,
+      clientReqId: params.clientReqId,
+      timeout: setTimeout(() => {
+        const queue = params.state.pendingAcksBySession.get(params.sessionId);
+        if (!queue) {
+          if (params.clientReqId) {
+            params.state.pendingAcksByClientReqId.delete(params.clientReqId);
+          }
+          reject(new Error(`[${params.accountId}] timeout waiting sider ack`));
+          return;
+        }
+        const idx = queue.indexOf(pendingAck);
+        if (idx >= 0) {
+          queue.splice(idx, 1);
+          if (queue.length === 0) {
+            params.state.pendingAcksBySession.delete(params.sessionId);
+          }
+        }
+        if (params.clientReqId) {
+          params.state.pendingAcksByClientReqId.delete(params.clientReqId);
+        }
+        reject(new Error(`[${params.accountId}] timeout waiting sider ack`));
+      }, params.timeoutMs),
+      resolve,
+      reject,
+    };
+    const queue = params.state.pendingAcksBySession.get(params.sessionId) ?? [];
+    queue.push(pendingAck);
+    params.state.pendingAcksBySession.set(params.sessionId, queue);
+    if (params.clientReqId) {
+      params.state.pendingAcksByClientReqId.set(params.clientReqId, pendingAck);
+    }
+  });
+}
+
+function readAckToken(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed || undefined;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return undefined;
+}
+
+function resolveAckSessionId(frame: SiderInboundAck): string | undefined {
+  const record = frame as Record<string, unknown>;
+  return (
+    readAckToken(record.session_id) ??
+    readAckToken(record.sessionId) ??
+    readAckToken(record.conversation_id) ??
+    readAckToken(record.conversationId)
+  );
+}
+
+function resolveAckClientReqId(frame: SiderInboundAck): string | undefined {
+  const record = frame as Record<string, unknown>;
+  return (
+    readAckToken(record.client_req_id) ??
+    readAckToken(record.clientReqId) ??
+    readAckToken(record.request_id) ??
+    readAckToken(record.requestId)
+  );
+}
+
+function resolveAckId(frame: SiderInboundAck): string | undefined {
+  const record = frame as Record<string, unknown>;
+  return (
+    readAckToken(record.id) ??
+    readAckToken(record.message_id) ??
+    readAckToken(record.messageId) ??
+    readAckToken(record.event_id) ??
+    readAckToken(record.eventId) ??
+    readAckToken(record.ack_id) ??
+    readAckToken(record.ackId)
+  );
+}
+
+function countPendingAcks(state: SiderRelaySocketState): number {
+  let count = 0;
+  for (const queue of state.pendingAcksBySession.values()) {
+    count += queue.length;
+  }
+  return count;
+}
+
+function detachPendingAck(state: SiderRelaySocketState, pendingAck: SiderPendingAck): void {
+  const queue = state.pendingAcksBySession.get(pendingAck.sessionId);
+  if (queue) {
+    const index = queue.indexOf(pendingAck);
+    if (index >= 0) {
+      queue.splice(index, 1);
+      if (queue.length === 0) {
+        state.pendingAcksBySession.delete(pendingAck.sessionId);
+      }
+    }
+  }
+  if (pendingAck.clientReqId) {
+    const existing = state.pendingAcksByClientReqId.get(pendingAck.clientReqId);
+    if (existing === pendingAck) {
+      state.pendingAcksByClientReqId.delete(pendingAck.clientReqId);
+    }
+  }
+}
+
+function settlePendingAck(params: {
+  accountId: string;
+  state: SiderRelaySocketState;
+  pendingAck: SiderPendingAck;
+  ackId?: string;
+  ackClientReqId?: string;
+}): boolean {
+  detachPendingAck(params.state, params.pendingAck);
+  clearTimeout(params.pendingAck.timeout);
+  const resolvedId = params.ackId ?? params.ackClientReqId ?? params.pendingAck.clientReqId;
+  if (!resolvedId) {
+    params.pendingAck.reject(
+      new Error(
+        `[${params.accountId}] ack missing id for session ${params.pendingAck.sessionId}`,
+      ),
+    );
+    return true;
+  }
+  params.pendingAck.resolve(resolvedId);
+  return true;
+}
+
+function resolveManagedAck(params: {
+  accountId: string;
+  frame: SiderInboundAck;
+}): boolean {
+  const state = siderRelaySockets.get(params.accountId);
+  if (!state || countPendingAcks(state) === 0) {
+    return false;
+  }
+  const ackSession = resolveAckSessionId(params.frame);
+  const ackId = resolveAckId(params.frame);
+  const ackClientReqId = resolveAckClientReqId(params.frame);
+
+  if (ackClientReqId) {
+    const pendingByReq = state.pendingAcksByClientReqId.get(ackClientReqId);
+    if (pendingByReq) {
+      return settlePendingAck({
+        accountId: params.accountId,
+        state,
+        pendingAck: pendingByReq,
+        ackId,
+        ackClientReqId,
+      });
+    }
+  }
+
+  if (ackSession) {
+    const queue = state.pendingAcksBySession.get(ackSession);
+    if (queue && queue.length > 0) {
+      const pendingAck = queue[0]!;
+      return settlePendingAck({
+        accountId: params.accountId,
+        state,
+        pendingAck,
+        ackId,
+        ackClientReqId,
+      });
+    }
+  }
+
+  if (countPendingAcks(state) === 1) {
+    for (const queue of state.pendingAcksBySession.values()) {
+      const pendingAck = queue[0];
+      if (pendingAck) {
+        return settlePendingAck({
+          accountId: params.accountId,
+          state,
+          pendingAck,
+          ackId,
+          ackClientReqId,
+        });
+      }
+    }
+  }
+
+  return false;
+}
+
+function resolveFrameClientReqId(frame: Record<string, unknown>): string | undefined {
+  return readAckToken(frame.client_req_id) ?? readAckToken(frame.clientReqId);
+}
+
+function isAckTimeoutError(error: unknown): boolean {
+  const text = String(error ?? "");
+  return text.includes("timeout waiting sider ack");
+}
+
+async function sendRelayFrameWithAck(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  frame: Record<string, unknown>;
+  timeoutMs: number;
+}): Promise<string> {
+  const { ws, state } = await waitForRelaySocketReady({
+    account: params.account,
+    timeoutMs: params.account.connectTimeoutMs,
+  });
+  ensureRelaySocketSessionSubscription({
+    account: params.account,
+    sessionId: params.sessionId,
+    ws,
+    state,
+  });
+  const ackPromise = waitForManagedAck({
+    state,
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    timeoutMs: params.timeoutMs,
+    clientReqId: resolveFrameClientReqId(params.frame),
+  });
+  try {
+    ws.send(JSON.stringify(params.frame));
+  } catch (err) {
+    clearRelaySocketState({
+      accountId: params.account.accountId,
+      expectedWs: ws,
+      closeSocket: true,
+      reason: `relay send failed: ${String(err)}`,
+    });
+    throw err;
+  }
+  return await ackPromise;
+}
+
+async function sendRelayFrameWithoutAck(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  frame: Record<string, unknown>;
+}): Promise<void> {
+  const { ws, state } = await waitForRelaySocketReady({
+    account: params.account,
+    timeoutMs: params.account.connectTimeoutMs,
+  });
+  ensureRelaySocketSessionSubscription({
+    account: params.account,
+    sessionId: params.sessionId,
+    ws,
+    state,
+  });
+  try {
+    ws.send(JSON.stringify(params.frame));
+  } catch (err) {
+    clearRelaySocketState({
+      accountId: params.account.accountId,
+      expectedWs: ws,
+      closeSocket: true,
+      reason: `relay send failed: ${String(err)}`,
+    });
+    throw err;
+  }
+}
+
+async function connectRelaySocket(params: {
+  account: ResolvedSiderAccount;
+  relayId: string;
+  subscribeSessionIds?: string[];
+}): Promise<WebSocket> {
+  const wsUrl = resolveRelayWsUrl(params.account.gatewayUrl);
+  const authorizedWsUrl = appendTokenQuery(wsUrl, params.account.token);
+  const subscribeSessionIds = Array.from(
+    new Set((params.subscribeSessionIds ?? []).map((item) => item.trim()).filter(Boolean)),
+  );
+  logDebug("opening sider relay websocket", {
+    accountId: params.account.accountId,
+    wsUrl,
+    relayId: params.relayId,
+    subscribeSessionCount: subscribeSessionIds.length,
+    hasTokenQuery: Boolean(params.account.token?.trim()),
+  });
+  const ws = createSiderWebSocket(authorizedWsUrl);
+  await waitForSocketOpen({
+    ws,
+    timeoutMs: params.account.connectTimeoutMs,
+    accountId: params.account.accountId,
+  });
+  const registerPayload: Record<string, unknown> = {
+    type: "register",
+    relay_id: params.relayId,
+  };
+  if (params.account.token) {
+    registerPayload.token = params.account.token;
+  }
+  ws.send(JSON.stringify(registerPayload));
+  if (subscribeSessionIds.length > 0) {
+    ws.send(
+      JSON.stringify({
+        type: "subscribe",
+        session_ids: subscribeSessionIds,
+      }),
+    );
+  }
+  return ws;
+}
+
+async function sendMessageToSider(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  parts: SiderPart[];
+  meta?: Record<string, unknown>;
+}): Promise<{ messageId: string; conversationId: string }> {
+  if (params.parts.length === 0) {
+    throw new Error("Cannot send sider message with empty parts");
+  }
+  const clientReqId = crypto.randomUUID();
+  let messageId: string = clientReqId;
+  let acked = false;
+  const frame: Record<string, unknown> = {
+    type: "message",
+    session_id: params.sessionId,
+    client_req_id: clientReqId,
+    parts: params.parts,
+    meta: params.meta ?? {},
+  };
+  try {
+    messageId = await sendRelayFrameWithAck({
+      account: params.account,
+      sessionId: params.sessionId,
+      timeoutMs: params.account.sendTimeoutMs,
+      frame,
+    });
+    acked = true;
+  } catch (err) {
+    if (!isAckTimeoutError(err)) {
+      throw err;
+    }
+    // Some gateway builds do not emit ack for message/event frames.
+    // The frame has already been sent on the socket; treat timeout as
+    // unconfirmed success to avoid dropping post-stream final messages.
+    logWarn("sider outbound ack timeout; treating message as sent", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      clientReqId,
+      timeoutMs: params.account.sendTimeoutMs,
+    });
+  }
+  logDebug("sider outbound message dispatched", {
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    clientReqId,
+    messageId,
+    acked,
+  });
+  return { messageId, conversationId: params.sessionId };
+}
+
+async function sendEventToSider(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  eventType: string;
+  payload: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}): Promise<{ eventId: string; conversationId: string }> {
+  const clientReqId = crypto.randomUUID();
+  await sendRelayFrameWithoutAck({
+    account: params.account,
+    sessionId: params.sessionId,
+    frame: {
+      type: "event",
+      session_id: params.sessionId,
+      client_req_id: clientReqId,
+      event_type: params.eventType,
+      payload: params.payload,
+      meta: params.meta ?? {},
+    },
+  });
+  return { eventId: clientReqId, conversationId: params.sessionId };
+}
+
+async function sendSiderEventBestEffort(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  event: SiderSampleEvent;
+  context: string;
+}): Promise<void> {
+  try {
+    await sendEventToSider({
+      account: params.account,
+      sessionId: params.sessionId,
+      eventType: params.event.eventType,
+      payload: params.event.payload,
+      meta: params.event.meta,
+    });
+  } catch (err) {
+    logWarn("sider outbound event failed", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      eventType: params.event.eventType,
+      context: params.context,
+      error: String(err),
+    });
+  }
+}
+
+async function sendSiderMessageBestEffort(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  parts: SiderPart[];
+  meta?: Record<string, unknown>;
+  context: string;
+}): Promise<void> {
+  try {
+    await sendMessageToSider({
+      account: params.account,
+      sessionId: params.sessionId,
+      parts: params.parts,
+      meta: params.meta,
+    });
+  } catch (err) {
+    logWarn("sider outbound message failed", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      partTypes: params.parts.map((part) => part.type),
+      context: params.context,
+      error: String(err),
+    });
+  }
+}
+
+function parseTextFromPart(part: SiderPart): string | null {
+  if (part.type !== "core.text") {
+    return null;
+  }
+  const payload = toRecord(part.payload);
+  if (payload?.text && typeof payload.text === "string") {
+    const text = payload.text.trim();
+    return text || null;
+  }
+  if (typeof part.payload === "string") {
+    const text = part.payload.trim();
+    return text || null;
+  }
+  return null;
+}
+
+function parseMediaFromPart(part: SiderPart): ParsedInboundMedia | null {
+  if (part.type !== "core.media" && part.type !== "core.file") {
+    return null;
+  }
+  const payload = toRecord(part.payload);
+  if (!payload) {
+    return null;
+  }
+  const readString = (value: unknown): string | undefined => {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+  };
+  const url =
+    readString(payload.download_url) ??
+    readString(payload.downloadUrl) ??
+    readString(payload.url) ??
+    readString(payload.resource_url) ??
+    readString(payload.resourceUrl) ??
+    readString(payload.media_url) ??
+    readString(payload.mediaUrl);
+  const objectKey = readString(payload.object_key) ?? readString(payload.objectKey);
+  const fileId = readString(payload.file_id) ?? readString(payload.fileId);
+  if (!url && !objectKey && !fileId) {
+    return null;
+  }
+  const mimeType =
+    readString(payload.mime) ??
+    readString(payload.mime_type) ??
+    readString(payload.mimeType) ??
+    readString(payload.content_type) ??
+    readString(payload.contentType);
+  const fileName =
+    readString(payload.name) ?? readString(payload.file_name) ?? readString(payload.fileName);
+  return {
+    ...(url ? { url } : {}),
+    ...(objectKey ? { objectKey } : {}),
+    ...(fileId ? { fileId } : {}),
+    ...(mimeType ? { mimeType } : {}),
+    ...(fileName ? { fileName } : {}),
+  };
+}
+
+function describeInboundMediaReference(item: ParsedInboundMedia): string | undefined {
+  if (item.url?.trim()) {
+    return item.url.trim();
+  }
+  if (item.objectKey?.trim()) {
+    return `sider-object-key:${item.objectKey.trim()}`;
+  }
+  if (item.fileId?.trim()) {
+    return `sider-file-id:${item.fileId.trim()}`;
+  }
+  return undefined;
+}
+
+function buildEventMeta(params: { accountId: string }): Record<string, unknown> {
+  return {
+    channel: SIDER_CHANNEL_ID,
+    account_id: params.accountId,
+    plugin_version: SIDER_PLUGIN_VERSION,
+    schema_version: 1,
+  };
+}
+
+function formatUsageForMessageMeta(usage?: SiderUsageTotals): Record<string, unknown> | undefined {
+  if (!hasNonZeroUsageTotals(usage)) {
+    return undefined;
+  }
+  return {
+    ...(hasFiniteNumber(usage?.input) ? { input: usage.input } : {}),
+    ...(hasFiniteNumber(usage?.output) ? { output: usage.output } : {}),
+    ...(hasFiniteNumber(usage?.cacheRead) ? { cache_read: usage.cacheRead } : {}),
+    ...(hasFiniteNumber(usage?.cacheWrite) ? { cache_write: usage.cacheWrite } : {}),
+    ...(hasFiniteNumber(usage?.total) ? { total: usage.total } : {}),
+  };
+}
+
+function parseUsageTotals(value: unknown): SiderUsageTotals | undefined {
+  const record = toRecord(value);
+  if (!record) {
+    return undefined;
+  }
+  const promptTokensDetails =
+    toRecord(record.prompt_tokens_details) ?? toRecord(record.promptTokensDetails);
+  const input = firstUsageCount(
+    record.input,
+    record.inputTokens,
+    record.input_tokens,
+    record.promptTokens,
+    record.prompt_tokens,
+  );
+  const output = firstUsageCount(
+    record.output,
+    record.outputTokens,
+    record.output_tokens,
+    record.completionTokens,
+    record.completion_tokens,
+  );
+  const cacheRead = firstUsageCount(
+    record.cacheRead,
+    record.cache_read,
+    record.cacheReadTokens,
+    record.cache_read_tokens,
+    record.cache_read_input_tokens,
+    record.cached_input_tokens,
+    record.cached_tokens,
+    promptTokensDetails?.cached_tokens,
+    promptTokensDetails?.cachedTokens,
+  );
+  const cacheWrite = firstUsageCount(
+    record.cacheWrite,
+    record.cache_write,
+    record.cacheWriteTokens,
+    record.cache_write_tokens,
+    record.cacheWriteInputTokens,
+    record.cache_write_input_tokens,
+    record.cache_creation_input_tokens,
+  );
+  const total = firstUsageCount(record.total, record.totalTokens, record.total_tokens);
+
+  const usage: SiderUsageTotals = {
+    ...(hasFiniteNumber(input) ? { input } : {}),
+    ...(hasFiniteNumber(output) ? { output } : {}),
+    ...(hasFiniteNumber(cacheRead) ? { cacheRead } : {}),
+    ...(hasFiniteNumber(cacheWrite) ? { cacheWrite } : {}),
+    ...(hasFiniteNumber(total) ? { total } : {}),
+  };
+
+  if (!hasFiniteNumber(usage.total) && hasUsageTotals(usage)) {
+    usage.total =
+      (hasFiniteNumber(usage.input) ? usage.input : 0) +
+      (hasFiniteNumber(usage.output) ? usage.output : 0) +
+      (hasFiniteNumber(usage.cacheRead) ? usage.cacheRead : 0) +
+      (hasFiniteNumber(usage.cacheWrite) ? usage.cacheWrite : 0);
+  }
+
+  return hasUsageTotals(usage) ? usage : undefined;
+}
+
+function choosePreferredUsageTotals(
+  ...candidates: Array<SiderUsageTotals | undefined>
+): SiderUsageTotals | undefined {
+  for (const candidate of candidates) {
+    if (candidate && hasNonZeroUsageTotals(candidate)) {
+      return candidate;
+    }
+  }
+  for (const candidate of candidates) {
+    if (candidate && hasUsageTotals(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+function parseUsageFromAssistantLike(value: unknown): SiderUsageTotals | undefined {
+  const record = toRecord(value);
+  if (!record) {
+    return undefined;
+  }
+  const meta = toRecord(record.meta);
+  const agentMeta =
+    toRecord(meta?.agentMeta) ??
+    toRecord(meta?.agent_meta) ??
+    toRecord(record.agentMeta) ??
+    toRecord(record.agent_meta);
+  return choosePreferredUsageTotals(
+    parseUsageTotals(record.usage),
+    parseUsageTotals(meta?.usage),
+    parseUsageTotals(meta?.lastCallUsage),
+    parseUsageTotals(meta?.last_call_usage),
+    parseUsageTotals(agentMeta?.usage),
+    parseUsageTotals(agentMeta?.lastCallUsage),
+    parseUsageTotals(agentMeta?.last_call_usage),
+  );
+}
+
+function buildMessageMeta(params: {
+  accountId: string;
+  runState?: SiderRunState;
+  stopReason?: string;
+}): Record<string, unknown> {
+  const meta = buildEventMeta({ accountId: params.accountId });
+  if (params.runState?.runId) {
+    meta.run_id = params.runState.runId;
+  }
+  if (params.runState?.provider) {
+    meta.provider = params.runState.provider;
+  }
+  if (params.runState?.model) {
+    meta.model = params.runState.model;
+  }
+  if (params.stopReason) {
+    meta.stop_reason = params.stopReason;
+  }
+  const usage = formatUsageForMessageMeta(params.runState?.usage);
+  if (usage) {
+    meta.usage = usage;
+  }
+  return meta;
+}
+
+function buildThinkingPart(text: string): SiderPart {
+  return {
+    type: "thinking",
+    spec_version: 1,
+    payload: { text },
+  };
+}
+
+function buildToolCallPart(params: {
+  callId: string;
+  toolName?: string;
+  toolCallId?: string;
+  runId?: string;
+  toolArgs?: unknown;
+}): SiderPart {
+  const payload: Record<string, unknown> = {
+    call_id: params.callId,
+    ...(params.toolName ? { tool_name: params.toolName } : {}),
+    ...(params.toolCallId ? { tool_call_id: params.toolCallId } : {}),
+    ...(params.runId ? { run_id: params.runId } : {}),
+  };
+  appendStructuredPayloadField(payload, "tool_args", params.toolArgs);
+  return {
+    type: "tool.call",
+    spec_version: 1,
+    payload,
+  };
+}
+
+function buildToolResultPart(params: {
+  callId: string;
+  toolName?: string;
+  toolCallId?: string;
+  runId?: string;
+  toolArgs?: unknown;
+  result?: unknown;
+  error?: string;
+  durationMs?: number;
+}): SiderPart {
+  const text = extractToolResultText(params.result);
+  const payload: Record<string, unknown> = {
+    call_id: params.callId,
+    ...(params.toolName ? { tool_name: params.toolName } : {}),
+    ...(params.toolCallId ? { tool_call_id: params.toolCallId } : {}),
+    ...(params.runId ? { run_id: params.runId } : {}),
+    ...(params.error ? { error: params.error } : {}),
+    ...(hasFiniteNumber(params.durationMs) ? { duration_ms: params.durationMs } : {}),
+    ...(text ? { text } : {}),
+    has_text: text.length > 0,
+    is_error: Boolean(params.error),
+  };
+  appendStructuredPayloadField(payload, "tool_args", params.toolArgs);
+  appendStructuredPayloadField(payload, "result", params.result);
+  return {
+    type: "tool.result",
+    spec_version: 1,
+    payload,
+  };
+}
+
+function parseAssistantOutput(lastAssistant: unknown): SiderParsedAssistantOutput | null {
+  const assistant = toRecord(lastAssistant);
+  if (!assistant) {
+    return null;
+  }
+  const content = Array.isArray(assistant.content) ? assistant.content : [];
+  const thinkingChunks: string[] = [];
+  const toolCalls: SiderParsedToolCall[] = [];
+  for (const item of content) {
+    const part = toRecord(item);
+    if (!part) {
+      continue;
+    }
+    const partType = typeof part.type === "string" ? part.type.trim() : "";
+    if (partType === "thinking") {
+      const thinking = typeof part.thinking === "string" ? part.thinking.trim() : "";
+      if (thinking) {
+        thinkingChunks.push(thinking);
+      }
+      continue;
+    }
+    if (partType !== "toolCall" && partType !== "toolUse") {
+      continue;
+    }
+    const toolName =
+      typeof part.toolName === "string"
+        ? part.toolName.trim()
+        : typeof part.name === "string"
+          ? part.name.trim()
+          : "";
+    const toolCallId =
+      typeof part.toolCallId === "string"
+        ? part.toolCallId.trim()
+        : typeof part.toolUseId === "string"
+          ? part.toolUseId.trim()
+          : typeof part.id === "string"
+            ? part.id.trim()
+            : undefined;
+    toolCalls.push({
+      toolName: toolName || undefined,
+      toolCallId: toolCallId || undefined,
+      toolArgs: part.arguments ?? part.input ?? part.args ?? part.parameters,
+    });
+  }
+  const stopReason = typeof assistant.stopReason === "string" ? assistant.stopReason.trim() : "";
+  return {
+    stopReason: stopReason || undefined,
+    thinkingText: thinkingChunks.join("\n\n").trim() || undefined,
+    toolCalls,
+  };
+}
+
+function buildTypingEvent(params: {
+  state: "typing" | "idle";
+  sessionId: string;
+  accountId: string;
+}): SiderSampleEvent {
+  return {
+    eventType: "typing",
+    payload: {
+      on: params.state === "typing",
+      state: params.state,
+      session_id: params.sessionId,
+      ts: Date.now(),
+    },
+    meta: buildEventMeta({ accountId: params.accountId }),
+  };
+}
+
+function buildStreamingStartEvent(params: {
+  sessionId: string;
+  streamId: string;
+  accountId: string;
+}): SiderSampleEvent {
+  return {
+    eventType: "stream.start",
+    payload: {
+      session_id: params.sessionId,
+      stream_id: params.streamId,
+      ts: Date.now(),
+    },
+    meta: buildEventMeta({ accountId: params.accountId }),
+  };
+}
+
+function buildStreamingDeltaEvent(params: {
+  sessionId: string;
+  streamId: string;
+  seq: number;
+  delta: string;
+  text: string;
+  accountId: string;
+}): SiderSampleEvent {
+  return {
+    eventType: "stream.delta",
+    payload: {
+      session_id: params.sessionId,
+      stream_id: params.streamId,
+      seq: params.seq,
+      delta: params.delta,
+      text: params.text,
+      done: false,
+      chunk_chars: params.delta.length,
+      ts: Date.now(),
+    },
+    meta: buildEventMeta({ accountId: params.accountId }),
+  };
+}
+
+function buildStreamingDoneEvent(params: {
+  sessionId: string;
+  streamId: string;
+  seq: number;
+  accountId: string;
+  reason: "final" | "interrupted";
+}): SiderSampleEvent {
+  return {
+    eventType: "stream.done",
+    payload: {
+      session_id: params.sessionId,
+      stream_id: params.streamId,
+      seq: params.seq,
+      done: true,
+      reason: params.reason,
+      ts: Date.now(),
+    },
+    meta: buildEventMeta({ accountId: params.accountId }),
+  };
+}
+
+function buildToolCallEvent(params: {
+  sessionId: string;
+  accountId: string;
+  seq: number;
+  callId: string;
+  phase: "start";
+  toolName?: string;
+  toolCallId?: string;
+  runId?: string;
+  sessionKey?: string;
+  toolArgs?: Record<string, unknown>;
+  error?: string;
+  durationMs?: number;
+}): SiderSampleEvent {
+  return {
+    eventType: "tool.call",
+    payload: {
+      session_id: params.sessionId,
+      seq: params.seq,
+      call_id: params.callId,
+      phase: params.phase,
+      tool_name: params.toolName,
+      tool_call_id: params.toolCallId,
+      run_id: params.runId,
+      session_key: params.sessionKey,
+      tool_args: params.toolArgs,
+      error: params.error,
+      duration_ms: params.durationMs,
+      ts: Date.now(),
+    },
+    meta: buildEventMeta({ accountId: params.accountId }),
+  };
+}
+
+function buildToolResultEvent(params: {
+  sessionId: string;
+  accountId: string;
+  seq: number;
+  callId: string;
+  toolName?: string;
+  toolCallId?: string;
+  runId?: string;
+  sessionKey?: string;
+  toolArgs?: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+  durationMs?: number;
+}): SiderSampleEvent {
+  const text = extractToolResultText(params.result);
+  const safeResult = toJsonSafeValue(params.result);
+  const safeToolArgs = toJsonSafeValue(params.toolArgs);
+  return {
+    eventType: "tool.result",
+    payload: {
+      session_id: params.sessionId,
+      seq: params.seq,
+      call_id: params.callId,
+      tool_name: params.toolName,
+      tool_call_id: params.toolCallId,
+      run_id: params.runId,
+      session_key: params.sessionKey,
+      tool_args: safeToolArgs,
+      result: safeResult,
+      error: params.error,
+      duration_ms: params.durationMs,
+      text,
+      has_text: text.trim().length > 0,
+      media_urls: [],
+      media_count: 0,
+      is_error: Boolean(params.error),
+      ts: Date.now(),
+    },
+    meta: buildEventMeta({ accountId: params.accountId }),
+  };
+}
+
+function resolveRelayCallIdForToolEvent(params: {
+  binding: SiderSessionBinding;
+  phase: "start" | "end" | "error";
+  toolCallId?: string;
+}): string {
+  if (params.toolCallId) {
+    const existing = params.binding.callIdByToolCallId.get(params.toolCallId);
+    if (existing) {
+      params.binding.currentToolCallId = existing;
+      return existing;
+    }
+    const created = crypto.randomUUID();
+    params.binding.callIdByToolCallId.set(params.toolCallId, created);
+    params.binding.currentToolCallId = created;
+    return created;
+  }
+  if (params.phase === "start" || !params.binding.currentToolCallId) {
+    params.binding.currentToolCallId = crypto.randomUUID();
+  }
+  return params.binding.currentToolCallId;
+}
+
+function clearRelayCallIdForToolEvent(params: {
+  binding: SiderSessionBinding;
+  callId: string;
+  toolCallId?: string;
+}): void {
+  if (params.toolCallId) {
+    params.binding.callIdByToolCallId.delete(params.toolCallId);
+  }
+  if (params.binding.currentToolCallId === params.callId) {
+    params.binding.currentToolCallId = undefined;
+  }
+}
+
+function resolveRunStateForOutbound(params: {
+  runId?: string;
+  sessionKey?: string;
+}): SiderRunState | undefined {
+  const direct = resolveSiderRunState(params.runId);
+  if (direct) {
+    return direct;
+  }
+  const binding = resolveSiderSessionBinding(params.sessionKey);
+  return resolveSiderRunState(binding?.currentRunId);
+}
+
+function buildPendingMessageContext(params: {
+  accountId: string;
+  runId?: string;
+  sessionKey?: string;
+  includeFinalThinking?: boolean;
+}): { parts: SiderPart[]; meta?: Record<string, unknown>; runId?: string } {
+  const runState = resolveRunStateForOutbound({
+    runId: params.runId,
+    sessionKey: params.sessionKey,
+  });
+  const parts: SiderPart[] = [];
+  if (runState?.pendingStructuredParts.length) {
+    parts.push(...runState.pendingStructuredParts);
+  }
+  if (params.includeFinalThinking && runState?.pendingFinalThinking) {
+    parts.push(buildThinkingPart(runState.pendingFinalThinking));
+  }
+  return {
+    parts,
+    meta: runState
+      ? buildMessageMeta({
+          accountId: params.accountId,
+          runState,
+          stopReason: params.includeFinalThinking ? runState.pendingFinalStopReason : undefined,
+        })
+      : undefined,
+    runId: runState?.runId,
+  };
+}
+
+function consumePendingMessageContext(params: {
+  runId?: string;
+  sessionKey?: string;
+  consumeFinalThinking?: boolean;
+}): void {
+  const runState = resolveRunStateForOutbound({
+    runId: params.runId,
+    sessionKey: params.sessionKey,
+  });
+  if (!runState) {
+    return;
+  }
+  runState.pendingStructuredParts = [];
+  if (params.consumeFinalThinking) {
+    runState.pendingFinalThinking = undefined;
+    runState.pendingFinalStopReason = undefined;
+  }
+}
+
+function clearBindingRunId(sessionKey?: string, runId?: string): void {
+  if (!sessionKey || !runId) {
+    return;
+  }
+  const binding = resolveSiderSessionBinding(sessionKey);
+  if (!binding) {
+    return;
+  }
+  if (binding.currentRunId === runId) {
+    binding.currentRunId = undefined;
+  }
+}
+
+export function recordSiderPersistedAgentMessage(params: {
+  sessionKey?: string;
+  message: unknown;
+}): void {
+  const binding = resolveSiderSessionBinding(params.sessionKey);
+  const runId = binding?.currentRunId;
+  if (!runId) {
+    return;
+  }
+  const message = toRecord(params.message);
+  if (!message) {
+    return;
+  }
+  const role = typeof message.role === "string" ? message.role.trim() : "";
+  if (role !== "assistant") {
+    return;
+  }
+  const runState = getOrCreateSiderRunState(runId);
+  runState.sessionKey = normalizeSessionBindingKey(params.sessionKey) ?? runState.sessionKey;
+  runState.sessionId = binding?.sessionId ?? runState.sessionId;
+  runState.accountId = binding?.account.accountId ?? runState.accountId;
+  runState.provider = typeof message.provider === "string" ? message.provider.trim() : runState.provider;
+  runState.model = typeof message.model === "string" ? message.model.trim() : runState.model;
+  const directUsage = parseUsageTotals(message.usage);
+  if (directUsage && hasNonZeroUsageTotals(directUsage)) {
+    addUsageTotals(runState.usage, directUsage);
+  } else if (!hasNonZeroUsageTotals(runState.usage)) {
+    const fallbackUsage = parseUsageFromAssistantLike(message);
+    if (fallbackUsage && hasNonZeroUsageTotals(fallbackUsage)) {
+      runState.usage = fallbackUsage;
+    }
+  }
+
+  const parsed = parseAssistantOutput(message);
+  if (!parsed) {
+    return;
+  }
+  if (parsed.toolCalls.length > 0 || parsed.stopReason === "toolUse") {
+    const parts: SiderPart[] = [];
+    if (parsed.thinkingText) {
+      parts.push(buildThinkingPart(parsed.thinkingText));
+    }
+    if (binding) {
+      for (const toolCall of parsed.toolCalls) {
+        const callId = resolveRelayCallIdForToolEvent({
+          binding,
+          phase: "start",
+          toolCallId: toolCall.toolCallId,
+        });
+        parts.push(
+          buildToolCallPart({
+            callId,
+            toolName: toolCall.toolName,
+            toolCallId: toolCall.toolCallId,
+            runId,
+            toolArgs: toolCall.toolArgs,
+          }),
+        );
+      }
+    }
+    if (parts.length > 0) {
+      runState.pendingStructuredParts.push(...parts);
+    }
+    return;
+  }
+
+  runState.pendingFinalThinking = parsed.thinkingText;
+  runState.pendingFinalStopReason = parsed.stopReason;
+}
+
+export function recordSiderLlmOutputUsage(params: {
+  sessionKey?: string;
+  runId?: string;
+  provider?: string;
+  model?: string;
+  usage?: unknown;
+  lastAssistant?: unknown;
+}): void {
+  const binding = resolveSiderSessionBinding(params.sessionKey);
+  const runId = params.runId || binding?.currentRunId;
+  if (!runId) {
+    return;
+  }
+  const runState = getOrCreateSiderRunState(runId);
+  runState.sessionKey = normalizeSessionBindingKey(params.sessionKey) ?? runState.sessionKey;
+  runState.sessionId = binding?.sessionId ?? runState.sessionId;
+  runState.accountId = binding?.account.accountId ?? runState.accountId;
+  if (params.provider && typeof params.provider === "string") {
+    runState.provider = params.provider.trim();
+  }
+  if (params.model && typeof params.model === "string") {
+    runState.model = params.model.trim();
+  }
+  const parsed = choosePreferredUsageTotals(
+    parseUsageTotals(params.usage),
+    parseUsageFromAssistantLike(params.lastAssistant),
+  );
+  if (parsed && hasNonZeroUsageTotals(parsed)) {
+    // llm_output provides the accumulated run usage — overwrite rather than add
+    // to avoid double-counting with before_message_write contributions.
+    runState.usage = parsed;
+  }
+}
+
+export async function emitSiderToolHookEvent(params: SiderToolHookPayload): Promise<void> {
+  const binding = resolveSiderSessionBinding(params.sessionKey);
+  if (!binding) {
+    logDebug("skip sider tool hook event: session binding not found", {
+      sessionKey: params.sessionKey,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      phase: params.phase,
+    });
+    return;
+  }
+  if (params.runId) {
+    binding.currentRunId = params.runId;
+  }
+
+  // sessions_send has a few easy-to-miss misuse patterns that look like
+  // channel/plugin failures in logs. Emit explicit diagnostics for triage.
+  const normalizedToolName = (params.toolName ?? "").trim().toLowerCase();
+  const toolArgs = toRecord(params.params);
+  const currentSessionKey = normalizeSessionBindingKey(params.sessionKey);
+  const targetSessionKeyRaw = typeof toolArgs?.sessionKey === "string" ? toolArgs.sessionKey : undefined;
+  const targetSessionKey = normalizeSessionBindingKey(targetSessionKeyRaw);
+  const hasAttachmentLikeArgs = Boolean(
+    toolArgs &&
+      [
+        "attachments",
+        "attachment",
+        "media",
+        "mediaUrl",
+        "mediaUrls",
+        "file",
+        "files",
+        "buffer",
+        "content",
+        "contentBase64",
+      ].some((field) => Object.prototype.hasOwnProperty.call(toolArgs, field)),
+  );
+
+  if (normalizedToolName === "sessions_send" && params.phase === "start") {
+    if (hasAttachmentLikeArgs) {
+      logWarn("sider observed sessions_send with attachment-like args; sessions_send only forwards text/message args", {
+        accountId: binding.account.accountId,
+        sessionId: binding.sessionId,
+        runId: params.runId,
+        sessionKey: params.sessionKey,
+        targetSessionKey: targetSessionKeyRaw,
+        toolCallId: params.toolCallId,
+      });
+    }
+    if (currentSessionKey && targetSessionKey && currentSessionKey === targetSessionKey) {
+      logWarn("sider observed sessions_send targeting current session; this often times out while current run is still active", {
+        accountId: binding.account.accountId,
+        sessionId: binding.sessionId,
+        runId: params.runId,
+        sessionKey: params.sessionKey,
+        targetSessionKey: targetSessionKeyRaw,
+        toolCallId: params.toolCallId,
+      });
+    }
+  }
+
+  const callId = resolveRelayCallIdForToolEvent({
+    binding,
+    phase: params.phase,
+    toolCallId: params.toolCallId,
+  });
+  if (params.phase === "start") {
+    binding.toolSeq += 1;
+    const toolCallEvent = buildToolCallEvent({
+      sessionId: binding.sessionId,
+      accountId: binding.account.accountId,
+      seq: binding.toolSeq,
+      callId,
+      phase: "start",
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      runId: params.runId,
+      sessionKey: params.sessionKey,
+      toolArgs: params.params,
+      error: params.error,
+      durationMs: params.durationMs,
+    });
+    await sendSiderEventBestEffort({
+      account: binding.account,
+      sessionId: binding.sessionId,
+      event: toolCallEvent,
+      context: "tool.call.hook.start",
+    });
+  }
+
+  if (params.phase !== "start") {
+    if (normalizedToolName === "sessions_send") {
+      const resultRecord = toRecord(params.result);
+      const status =
+        typeof resultRecord?.status === "string" ? resultRecord.status.trim().toLowerCase() : "";
+      if (status === "timeout") {
+        logWarn("sider observed sessions_send timeout", {
+          accountId: binding.account.accountId,
+          sessionId: binding.sessionId,
+          runId: params.runId,
+          sessionKey: params.sessionKey,
+          targetSessionKey: targetSessionKeyRaw,
+          toolCallId: params.toolCallId,
+          error: params.error,
+          durationMs: params.durationMs,
+          selfTargeted: Boolean(currentSessionKey && targetSessionKey && currentSessionKey === targetSessionKey),
+          hasAttachmentLikeArgs,
+        });
+      }
+    }
+    binding.toolSeq += 1;
+    const toolResultEvent = buildToolResultEvent({
+      sessionId: binding.sessionId,
+      accountId: binding.account.accountId,
+      seq: binding.toolSeq,
+      callId,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      runId: params.runId,
+      sessionKey: params.sessionKey,
+      toolArgs: params.params,
+      result: params.result,
+      error: params.error,
+      durationMs: params.durationMs,
+    });
+    await sendSiderEventBestEffort({
+      account: binding.account,
+      sessionId: binding.sessionId,
+      event: toolResultEvent,
+      context: `tool.result.hook.${params.phase}`,
+    });
+    if (params.runId) {
+      const runState = getOrCreateSiderRunState(params.runId);
+      runState.sessionKey = normalizeSessionBindingKey(params.sessionKey) ?? runState.sessionKey;
+      runState.sessionId = binding.sessionId;
+      runState.accountId = binding.account.accountId;
+      runState.pendingStructuredParts.push(
+        buildToolResultPart({
+          callId,
+          toolName: params.toolName,
+          toolCallId: params.toolCallId,
+          runId: params.runId,
+          toolArgs: params.params,
+          result: params.result,
+          error: params.error,
+          durationMs: params.durationMs,
+        }),
+      );
+    }
+    clearRelayCallIdForToolEvent({
+      binding,
+      callId,
+      toolCallId: params.toolCallId,
+    });
+  }
+}
+
+async function openStreamingSessionIfNeeded(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  streamState: SiderStreamState;
+}): Promise<void> {
+  if (params.streamState.active && params.streamState.streamId) {
+    return;
+  }
+  params.streamState.active = true;
+  params.streamState.streamId = crypto.randomUUID();
+  params.streamState.seq = 0;
+  const streamStartEvent = buildStreamingStartEvent({
+    sessionId: params.sessionId,
+    streamId: params.streamState.streamId,
+    accountId: params.account.accountId,
+  });
+  await sendSiderEventBestEffort({
+    account: params.account,
+    sessionId: params.sessionId,
+    event: streamStartEvent,
+    context: "stream.start",
+  });
+}
+
+async function sendStreamingDeltaEvent(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  streamState: SiderStreamState;
+  delta: string;
+  text: string;
+  context: string;
+}): Promise<void> {
+  if (!params.delta) {
+    return;
+  }
+  await openStreamingSessionIfNeeded({
+    account: params.account,
+    sessionId: params.sessionId,
+    streamState: params.streamState,
+  });
+  params.streamState.seq += 1;
+  const streamDeltaEvent = buildStreamingDeltaEvent({
+    sessionId: params.sessionId,
+    streamId: params.streamState.streamId!,
+    seq: params.streamState.seq,
+    delta: params.delta,
+    text: params.text,
+    accountId: params.account.accountId,
+  });
+  logDebug("sending stream delta event", {
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    eventType: streamDeltaEvent.eventType,
+    streamId: params.streamState.streamId,
+    seq: params.streamState.seq,
+    deltaLength: params.delta.length,
+    textLength: params.text.length,
+    context: params.context,
+  });
+  await sendSiderEventBestEffort({
+    account: params.account,
+    sessionId: params.sessionId,
+    event: streamDeltaEvent,
+    context: params.context,
+  });
+}
+
+async function closeStreamingSessionIfActive(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  streamState: SiderStreamState;
+  reason: "final" | "interrupted";
+  context: string;
+}): Promise<void> {
+  if (!params.streamState.active || !params.streamState.streamId) {
+    return;
+  }
+  params.streamState.seq += 1;
+  const streamDoneEvent = buildStreamingDoneEvent({
+    sessionId: params.sessionId,
+    streamId: params.streamState.streamId,
+    seq: params.streamState.seq,
+    accountId: params.account.accountId,
+    reason: params.reason,
+  });
+  await sendSiderEventBestEffort({
+    account: params.account,
+    sessionId: params.sessionId,
+    event: streamDoneEvent,
+    context: params.context,
+  });
+  params.streamState.active = false;
+  params.streamState.streamId = undefined;
+  params.streamState.seq = 0;
+}
+
+function enqueueStreamEventTask(params: {
+  streamState: SiderStreamState;
+  task: () => Promise<void>;
+}): Promise<void> {
+  const next = params.streamState.streamEventQueue.then(params.task).catch((err) => {
+    logWarn("sider stream event queue task failed", {
+      error: String(err),
+    });
+  });
+  params.streamState.streamEventQueue = next;
+  return next;
+}
+
+async function flushStreamEventQueue(streamState: SiderStreamState): Promise<void> {
+  await streamState.streamEventQueue;
+}
+
+function derivePartialDelta(params: { previous: string; next: string }): string {
+  const prev = params.previous;
+  const next = params.next;
+  if (!next) {
+    return "";
+  }
+  if (!prev) {
+    return next;
+  }
+  if (next === prev) {
+    return "";
+  }
+  if (next.startsWith(prev)) {
+    return next.slice(prev.length);
+  }
+  if (prev.startsWith(next)) {
+    // Snapshot regressed (restart/truncation); wait for next stable snapshot.
+    return "";
+  }
+  const maxOverlap = Math.min(prev.length, next.length);
+  for (let overlap = maxOverlap; overlap > 0; overlap -= 1) {
+    if (prev.endsWith(next.slice(0, overlap))) {
+      return next.slice(overlap);
+    }
+  }
+  return next;
+}
+
+function mergeBlockTextIntoStreamState(params: {
+  streamState: SiderStreamState;
+  text: string;
+}): void {
+  const next = params.text;
+  if (!next) {
+    return;
+  }
+  const prev = params.streamState.accumulatedBlockText;
+  if (!prev) {
+    params.streamState.accumulatedBlockText = next;
+    return;
+  }
+  if (next.startsWith(prev)) {
+    // Some runtimes emit cumulative text snapshots.
+    params.streamState.accumulatedBlockText = next;
+    return;
+  }
+  if (prev.endsWith(next)) {
+    // Avoid duplicating identical trailing chunks.
+    return;
+  }
+  params.streamState.accumulatedBlockText += next;
+}
+
+async function handleStreamingPartialSnapshot(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  streamState: SiderStreamState;
+  snapshot: string;
+}): Promise<void> {
+  if (params.streamState.streamDeltaMode === "block") {
+    return;
+  }
+  if (params.streamState.streamDeltaMode === "undecided") {
+    params.streamState.streamDeltaMode = "partial";
+  }
+  if (!params.snapshot) {
+    return;
+  }
+  const delta = derivePartialDelta({
+    previous: params.streamState.partialSnapshot,
+    next: params.snapshot,
+  });
+  params.streamState.partialSnapshot = params.snapshot;
+  if (!delta) {
+    return;
+  }
+  // Partial callbacks carry the latest visible assistant snapshot.
+  params.streamState.accumulatedBlockText = params.snapshot;
+  await sendStreamingDeltaEvent({
+    account: params.account,
+    sessionId: params.sessionId,
+    streamState: params.streamState,
+    delta,
+    text: params.snapshot,
+    context: "stream.delta.partial",
+  });
+  params.streamState.partialDeltaCount += 1;
+}
+
+async function deliverReplyPayloadToSider(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  streamState: SiderStreamState;
+  payload: ReplyPayload;
+  kind: "tool" | "block" | "final";
+  mediaLocalRoots?: readonly string[];
+}): Promise<void> {
+  const payloadMediaUrls = resolveOutboundMediaUrls(params.payload);
+  if (params.kind === "block") {
+    const delta = typeof params.payload.text === "string" ? params.payload.text : "";
+    if (delta.length > 0) {
+      params.streamState.blockDeltaCount += 1;
+      mergeBlockTextIntoStreamState({
+        streamState: params.streamState,
+        text: delta,
+      });
+      if (params.streamState.streamDeltaMode !== "partial") {
+        if (params.streamState.streamDeltaMode === "undecided") {
+          params.streamState.streamDeltaMode = "block";
+        }
+        await sendStreamingDeltaEvent({
+          account: params.account,
+          sessionId: params.sessionId,
+          streamState: params.streamState,
+          delta,
+          text: params.streamState.accumulatedBlockText,
+          context: "stream.delta.block",
+        });
+      } else {
+        logDebug("skip block stream delta because partial streaming mode is active", {
+          accountId: params.account.accountId,
+          sessionId: params.sessionId,
+          deltaLength: delta.length,
+          partialDeltaCount: params.streamState.partialDeltaCount,
+          streamDeltaMode: params.streamState.streamDeltaMode,
+        });
+      }
+    }
+    if (payloadMediaUrls.length === 0) {
+      return;
+    }
+    logDebug("block payload contains media; sending persisted sider message", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      mediaCount: payloadMediaUrls.length,
+      hasText: delta.length > 0,
+    });
+  }
+
+  if (params.kind === "final") {
+    await flushStreamEventQueue(params.streamState);
+    if (!params.streamState.active && params.streamState.blockDeltaCount === 0) {
+      const finalText = typeof params.payload.text === "string" ? params.payload.text : "";
+      if (finalText.length > 0) {
+        logDebug("no block delta observed; sending synthetic stream events from final payload", {
+          accountId: params.account.accountId,
+          sessionId: params.sessionId,
+          textLength: finalText.length,
+        });
+        params.streamState.accumulatedBlockText = finalText;
+        await sendStreamingDeltaEvent({
+          account: params.account,
+          sessionId: params.sessionId,
+          streamState: params.streamState,
+          delta: finalText,
+          text: finalText,
+          context: "stream.delta.final-fallback",
+        });
+      }
+    }
+
+    await closeStreamingSessionIfActive({
+      account: params.account,
+      sessionId: params.sessionId,
+      streamState: params.streamState,
+      reason: "final",
+      context: "stream.done",
+    });
+
+    // Do not persist final message inside the deliver callback. `llm_output`
+    // is emitted at run tail (after callbacks complete), so persisting later
+    // avoids racing usage/meta population.
+    params.streamState.pendingFinalPayload = params.payload;
+    return;
+  }
+
+  const baseParts = await buildSiderPartsFromReplyPayload({
+    account: params.account,
+    sessionId: params.sessionId,
+    payload: params.payload,
+    mediaLocalRoots: params.mediaLocalRoots,
+    logger: {
+      debug: logDebug,
+      warn: logWarn,
+    },
+  });
+  const messageContext = buildPendingMessageContext({
+    accountId: params.account.accountId,
+    runId: params.streamState.currentRunId,
+    sessionKey: params.streamState.sessionKey,
+    includeFinalThinking: false,
+  });
+  if (baseParts.length === 0) {
+    logDebug("skip sider outbound message: base parts empty while pending structured parts are buffered", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      kind: params.kind,
+      pendingPartTypes: messageContext.parts.map((part) => part.type),
+    });
+    return;
+  }
+  const parts = [...messageContext.parts, ...baseParts];
+  if (parts.length === 0) {
+    logDebug("skip sider outbound message: empty parts", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      kind: params.kind,
+      hasText: typeof params.payload.text === "string" && params.payload.text.length > 0,
+      mediaCount: payloadMediaUrls.length,
+    });
+    return;
+  }
+  logDebug("sending sider outbound message from payload", {
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    kind: params.kind,
+    partTypes: parts.map((part) => part.type),
+    mediaCount: payloadMediaUrls.length,
+  });
+  await sendMessageToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    parts,
+    meta: messageContext.meta,
+  });
+  consumePendingMessageContext({
+    runId: messageContext.runId,
+    sessionKey: params.streamState.sessionKey,
+    consumeFinalThinking: false,
+  });
+
+  if (payloadMediaUrls.length > 0) {
+    params.streamState.persistedFinalText = true;
+  }
+}
+
+async function persistDeferredFinalReplyPayloadToSider(params: {
+  account: ResolvedSiderAccount;
+  sessionId: string;
+  streamState: SiderStreamState;
+  payload: ReplyPayload;
+  mediaLocalRoots?: readonly string[];
+}): Promise<void> {
+  const payloadMediaUrls = resolveOutboundMediaUrls(params.payload);
+  const baseParts = await buildSiderPartsFromReplyPayload({
+    account: params.account,
+    sessionId: params.sessionId,
+    payload: params.payload,
+    mediaLocalRoots: params.mediaLocalRoots,
+    logger: {
+      debug: logDebug,
+      warn: logWarn,
+    },
+  });
+  const messageContext = buildPendingMessageContext({
+    accountId: params.account.accountId,
+    runId: params.streamState.currentRunId,
+    sessionKey: params.streamState.sessionKey,
+    includeFinalThinking: true,
+  });
+  if (
+    baseParts.length === 0 &&
+    messageContext.parts.length > 0 &&
+    params.streamState.accumulatedBlockText.trim()
+  ) {
+    logDebug("deferred final payload has no base parts; keeping pending context for text fallback", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      runId: params.streamState.currentRunId,
+      pendingPartTypes: messageContext.parts.map((part) => part.type),
+    });
+    return;
+  }
+  const parts = [...messageContext.parts, ...baseParts];
+  if (parts.length === 0) {
+    logDebug("skip deferred final sider message: empty parts", {
+      accountId: params.account.accountId,
+      sessionId: params.sessionId,
+      runId: params.streamState.currentRunId,
+      hasAccumulatedText: params.streamState.accumulatedBlockText.trim().length > 0,
+    });
+    if (!params.streamState.accumulatedBlockText.trim()) {
+      clearBindingRunId(params.streamState.sessionKey, messageContext.runId);
+      discardSiderRunState(messageContext.runId);
+      params.streamState.currentRunId = undefined;
+    }
+    return;
+  }
+  logDebug("sending deferred final sider outbound message from payload", {
+    accountId: params.account.accountId,
+    sessionId: params.sessionId,
+    runId: params.streamState.currentRunId,
+    partTypes: parts.map((part) => part.type),
+    mediaCount: payloadMediaUrls.length,
+  });
+  await sendMessageToSider({
+    account: params.account,
+    sessionId: params.sessionId,
+    parts,
+    meta: messageContext.meta,
+  });
+  consumePendingMessageContext({
+    runId: messageContext.runId,
+    sessionKey: params.streamState.sessionKey,
+    consumeFinalThinking: true,
+  });
+
+  if (baseParts.length > 0 || payloadMediaUrls.length > 0) {
+    params.streamState.persistedFinalText = true;
+  }
+
+  clearBindingRunId(params.streamState.sessionKey, messageContext.runId);
+  discardSiderRunState(messageContext.runId);
+  params.streamState.currentRunId = undefined;
+  params.streamState.accumulatedBlockText = "";
+  params.streamState.blockDeltaCount = 0;
+  params.streamState.partialDeltaCount = 0;
+  params.streamState.streamDeltaMode = "undecided";
+  params.streamState.partialSnapshot = "";
+}
+
+async function handleInboundRealtimeMessage(params: {
+  cfg: OpenClawConfig;
+  account: ResolvedSiderAccount;
+  event: SiderInboundRealtimeMessage;
+}): Promise<void> {
+  const { cfg, account, event } = params;
+  const core = getSiderRuntime();
+  const sessionId = typeof event.session_id === "string" ? event.session_id.trim() : "";
+  if (!sessionId) {
+    return;
+  }
+  if ((event.source_role ?? "").toLowerCase() === "relay") {
+    return;
+  }
+  const parts = Array.isArray(event.parts) ? event.parts : [];
+  const textChunks: string[] = [];
+  const mediaItems: ParsedInboundMedia[] = [];
+
+  for (const part of parts) {
+    const text = parseTextFromPart(part);
+    if (text) {
+      textChunks.push(text);
+      continue;
+    }
+    const media = parseMediaFromPart(part);
+    if (media) {
+      mediaItems.push(media);
+    }
+  }
+
+  const rawText = textChunks.join("\n").trim();
+  const mediaUrls = mediaItems.map((item) => item.url).filter((item): item is string => Boolean(item));
+  const parsedMediaTypes = mediaItems
+    .map((item) => item.mimeType)
+    .filter((item): item is string => Boolean(item));
+  const hasControlCommand = rawText ? core.channel.text.hasControlCommand(rawText, cfg) : false;
+  const shouldComputeCommandAuthorized = rawText
+    ? core.channel.commands.shouldComputeCommandAuthorized(rawText, cfg)
+    : false;
+  const commandAuthorized = shouldComputeCommandAuthorized
+    ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups: cfg.commands?.useAccessGroups !== false,
+        // Sider currently has no per-sender allowlist. Treat the authenticated relay session as trusted.
+        authorizers: [{ configured: true, allowed: true }],
+      })
+    : undefined;
+
+  if (!rawText && mediaItems.length === 0) {
+    logDebug("drop inbound sider message: no text/media", {
+      accountId: account.accountId,
+      sessionId,
+      messageId: event.message_id,
+      partTypes: parts.map((part) => part.type),
+    });
+    return;
+  }
+
+  if (hasControlCommand) {
+    logInfo("sider control command inbound", {
+      accountId: account.accountId,
+      sessionId,
+      messageId: event.message_id,
+      commandAuthorized,
+    });
+    logDebug("detected sider control command", {
+      accountId: account.accountId,
+      sessionId,
+      messageId: event.message_id,
+      commandBody: rawText,
+      shouldComputeCommandAuthorized,
+      commandAuthorized,
+    });
+  }
+
+  const resolvedInboundMedia = await resolveInboundSiderMedia({
+    runtime: core,
+    cfg,
+    accountId: account.accountId,
+    mediaItems,
+    gatewayUrl: account.gatewayUrl,
+    token: account.token,
+    requestTimeoutMs: account.sendTimeoutMs,
+    logger: {
+      debug: logDebug,
+      warn: logWarn,
+    },
+  });
+  const unresolvedMediaUrls = resolvedInboundMedia.unresolvedMedia
+    .map((item) => item.url)
+    .filter((item): item is string => Boolean(item));
+  const unresolvedMediaRefs = resolvedInboundMedia.unresolvedMedia
+    .map((item) => describeInboundMediaReference(item))
+    .filter((item): item is string => Boolean(item));
+  if (resolvedInboundMedia.unresolvedMedia.length > 0) {
+    logWarn("sider inbound media fallback to attachment url", {
+      accountId: account.accountId,
+      sessionId,
+      unresolvedCount: resolvedInboundMedia.unresolvedMedia.length,
+      unresolvedMediaRefs,
+    });
+  }
+  const bodyForAgent = formatTextWithAttachmentLinks(rawText, unresolvedMediaRefs);
+  const mediaPayload = resolvedInboundMedia.mediaPayload;
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: SIDER_CHANNEL_ID,
+    accountId: account.accountId,
+    peer: {
+      kind: "direct",
+      id: sessionId,
+    },
+  });
+  const to = `session:${sessionId}`;
+  const mediaLocalRoots = getAgentScopedMediaLocalRoots(cfg, route.agentId);
+  const timestamp =
+    typeof event.created_at === "number" && Number.isFinite(event.created_at)
+      ? event.created_at
+      : Date.now();
+
+  const envelopeBody = core.channel.reply.formatAgentEnvelope({
+    channel: "Sider",
+    from: sessionId,
+    timestamp,
+    envelope: core.channel.reply.resolveEnvelopeFormatOptions(cfg),
+    body: bodyForAgent,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: envelopeBody,
+    BodyForAgent: bodyForAgent,
+    RawBody: bodyForAgent,
+    CommandBody: rawText,
+    BodyForCommands: rawText,
+    meta: event.meta,
+    From: `${SIDER_CHANNEL_ID}:client:${sessionId}`,
+    To: to,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: "direct",
+    ConversationLabel: sessionId,
+    SenderId: "client",
+    SenderName: "client",
+    Provider: SIDER_CHANNEL_ID,
+    Surface: SIDER_CHANNEL_ID,
+    MessageSid: typeof event.message_id === "string" ? event.message_id : undefined,
+    Timestamp: timestamp,
+    WasMentioned: true,
+    OriginatingChannel: SIDER_CHANNEL_ID,
+    OriginatingTo: to,
+    ...mediaPayload,
+    MediaUrl:
+      mediaPayload.MediaUrl ||
+      (unresolvedMediaUrls.length > 0 ? unresolvedMediaUrls[0] : undefined),
+    MediaUrls:
+      mediaPayload.MediaUrls ||
+      (unresolvedMediaUrls.length > 0 ? unresolvedMediaUrls : undefined),
+    MediaType: mediaPayload.MediaType || parsedMediaTypes[0],
+    MediaTypes:
+      mediaPayload.MediaTypes ||
+      (parsedMediaTypes.length > 0 ? parsedMediaTypes : undefined),
+    CommandAuthorized: commandAuthorized,
+  });
+  rememberSiderSessionBinding({
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    account,
+    sessionId,
+  });
+
+  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      core.logging.getChildLogger({ channel: SIDER_CHANNEL_ID }).warn("sider failed to record session", {
+        error: String(err),
+      });
+    },
+  });
+
+  const typingParams: CreateTypingCallbacksParams = {
+    start: async () => {
+      const typingEvent = buildTypingEvent({
+        state: "typing",
+        sessionId,
+        accountId: account.accountId,
+      });
+      logDebug("sending typing start event", {
+        accountId: account.accountId,
+        sessionId,
+        eventType: typingEvent.eventType,
+      });
+      await sendSiderEventBestEffort({
+        account,
+        sessionId,
+        event: typingEvent,
+        context: "typing.start",
+      });
+    },
+    stop: async () => {
+      const typingEvent = buildTypingEvent({
+        state: "idle",
+        sessionId,
+        accountId: account.accountId,
+      });
+      logDebug("sending typing stop event", {
+        accountId: account.accountId,
+        sessionId,
+        eventType: typingEvent.eventType,
+      });
+      await sendSiderEventBestEffort({
+        account,
+        sessionId,
+        event: typingEvent,
+        context: "typing.stop",
+      });
+    },
+    onStartError: (err: unknown) => {
+      logWarn("sider typing start failed", {
+        accountId: account.accountId,
+        sessionId,
+        error: String(err),
+      });
+    },
+    onStopError: (err: unknown) => {
+      logWarn("sider typing stop failed", {
+        accountId: account.accountId,
+        sessionId,
+        error: String(err),
+      });
+    },
+  };
+
+  const { onModelSelected, typingCallbacks, ...prefixOptions } = createChannelReplyPipeline({
+    cfg,
+    agentId: route.agentId,
+    channel: SIDER_CHANNEL_ID,
+    accountId: account.accountId,
+    typing: typingParams,
+  });
+
+  logDebug("dispatching sider inbound message", {
+    accountId: account.accountId,
+    sessionId,
+    messageId: event.message_id,
+    routeSessionKey: route.sessionKey,
+    hasControlCommand,
+    commandAuthorized,
+    textLength: rawText.length,
+    mediaCount: mediaUrls.length,
+    mediaDownloadedCount: mediaPayload.MediaPaths?.length ?? 0,
+    mediaDownloadFailedCount: resolvedInboundMedia.unresolvedMedia.length,
+  });
+
+  const streamState: SiderStreamState = {
+    active: false,
+    streamId: undefined,
+    seq: 0,
+    blockDeltaCount: 0,
+    partialDeltaCount: 0,
+    streamDeltaMode: "undecided",
+    partialSnapshot: "",
+    accumulatedBlockText: "",
+    persistedFinalText: false,
+    pendingFinalPayload: undefined,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    currentRunId: undefined,
+    streamEventQueue: Promise.resolve(),
+  };
+
+  let dispatchCompleted = false;
+  try {
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        ...prefixOptions,
+        typingCallbacks,
+        deliver: async (payload, info) => {
+          // Skip compaction status notices — they are informational UI signals
+          // that should not be persisted as message content or accumulated into
+          // the outbound text.
+          if ((payload as Record<string, unknown>).isCompactionNotice === true) {
+            logDebug("skip sider deliver: compaction notice", {
+              accountId: account.accountId,
+              sessionId,
+              kind: info.kind,
+            });
+            return;
+          }
+          logDebug("sider dispatch deliver payload", {
+            accountId: account.accountId,
+            sessionId,
+            kind: info.kind,
+            hasText: typeof payload.text === "string" && payload.text.length > 0,
+            mediaCount: resolveOutboundMediaUrls(payload).length,
+          });
+          await deliverReplyPayloadToSider({
+            account,
+            sessionId,
+            streamState,
+            payload,
+            kind: info.kind,
+            mediaLocalRoots,
+          });
+        },
+        onError: (err, info) => {
+          core.logging
+            .getChildLogger({ channel: SIDER_CHANNEL_ID })
+            .error(`sider ${info.kind} reply failed`, { error: String(err) });
+        },
+      },
+      replyOptions: {
+        disableBlockStreaming: false,
+        onAgentRunStart: (runId) => {
+          streamState.currentRunId = runId;
+          const binding = resolveSiderSessionBinding(streamState.sessionKey);
+          if (binding) {
+            binding.currentRunId = runId;
+          }
+        },
+        onPartialReply: async (payload) => {
+          const snapshot = typeof payload.text === "string" ? payload.text : "";
+          if (!snapshot) {
+            return;
+          }
+          if (streamState.streamDeltaMode === "block") {
+            return;
+          }
+          if (streamState.streamDeltaMode === "undecided") {
+            streamState.streamDeltaMode = "partial";
+          }
+          await enqueueStreamEventTask({
+            streamState,
+            task: async () => {
+              await handleStreamingPartialSnapshot({
+                account,
+                sessionId,
+                streamState,
+                snapshot,
+              });
+            },
+          });
+        },
+        onCompactionStart: async () => {
+          // Flush any in-flight stream events and close the current streaming
+          // session so the gateway sees a clean break.  Do NOT clear
+          // accumulatedBlockText — the deliver callback already filters
+          // compaction notices via isCompactionNotice, and clearing the
+          // accumulated text would lose the deferred final message fallback.
+          await flushStreamEventQueue(streamState);
+          await closeStreamingSessionIfActive({
+            account,
+            sessionId,
+            streamState,
+            reason: "interrupted",
+            context: "stream.done.compaction-start",
+          });
+          // Reset stream delta tracking so post-compaction output starts
+          // a fresh streaming session without duplicating earlier deltas.
+          streamState.blockDeltaCount = 0;
+          streamState.partialDeltaCount = 0;
+          streamState.streamDeltaMode = "undecided";
+          streamState.partialSnapshot = "";
+          logDebug("sider stream state reset for compaction", {
+            accountId: account.accountId,
+            sessionId,
+          });
+        },
+        onModelSelected,
+      },
+    });
+    dispatchCompleted = true;
+    logDebug("completed sider inbound dispatch", {
+      accountId: account.accountId,
+      sessionId,
+      messageId: event.message_id,
+    });
+  } finally {
+    await flushStreamEventQueue(streamState);
+    await closeStreamingSessionIfActive({
+      account,
+      sessionId,
+      streamState,
+      reason: dispatchCompleted ? "final" : "interrupted",
+      context: dispatchCompleted ? "stream.done.dispatch-end" : "stream.done.interrupted",
+    });
+    streamState.blockDeltaCount = 0;
+  }
+
+  if (!dispatchCompleted) {
+    return;
+  }
+
+  const pendingFinalPayload = streamState.pendingFinalPayload;
+  streamState.pendingFinalPayload = undefined;
+  if (pendingFinalPayload) {
+    await persistDeferredFinalReplyPayloadToSider({
+      account,
+      sessionId,
+      streamState,
+      payload: pendingFinalPayload,
+      mediaLocalRoots,
+    });
+  }
+
+  if (!streamState.persistedFinalText && streamState.accumulatedBlockText.trim()) {
+    const text = streamState.accumulatedBlockText;
+    const messageContext = buildPendingMessageContext({
+      accountId: account.accountId,
+      runId: streamState.currentRunId,
+      sessionKey: streamState.sessionKey,
+      includeFinalThinking: true,
+    });
+    const baseParts = await buildSiderPartsFromReplyPayload({
+      account,
+      sessionId,
+      payload: {
+        text,
+      },
+      mediaLocalRoots,
+      logger: {
+        debug: logDebug,
+        warn: logWarn,
+      },
+    });
+    const parts = [...messageContext.parts, ...baseParts];
+    logDebug("no final message payload observed; persisting accumulated block text as final message", {
+      accountId: account.accountId,
+      sessionId,
+      textLength: text.length,
+      partTypes: parts.map((part) => part.type),
+      extraPartTypes: messageContext.parts.map((part) => part.type),
+    });
+    if (parts.length === 0) {
+      logDebug("skip fallback final sider message: empty parts", {
+        accountId: account.accountId,
+        sessionId,
+      });
+      return;
+    }
+    await sendMessageToSider({
+      account,
+      sessionId,
+      parts,
+      meta: messageContext.meta,
+    });
+    consumePendingMessageContext({
+      runId: messageContext.runId,
+      sessionKey: streamState.sessionKey,
+      consumeFinalThinking: true,
+    });
+    clearBindingRunId(streamState.sessionKey, messageContext.runId);
+    discardSiderRunState(messageContext.runId);
+    streamState.persistedFinalText = true;
+    streamState.currentRunId = undefined;
+    streamState.accumulatedBlockText = "";
+  }
+}
+
+async function monitorSiderSession(params: {
+  cfg: OpenClawConfig;
+  account: ResolvedSiderAccount;
+  abortSignal: AbortSignal;
+  log?: SiderMonitorLogger;
+}): Promise<void> {
+  const { cfg, account, abortSignal, log } = params;
+  let currentCfg = cfg;
+  let currentAccount = account;
+  const monitorLog = createMonitorLogger(log);
+
+  while (!abortSignal.aborted) {
+    let ws: WebSocket | null = null;
+    let skipSleep = false;
+    const subscribeSessionIds = currentAccount.subscribeSessionIds;
+    try {
+      monitorLog.info(`[${currentAccount.accountId}] opening sider relay websocket`, {
+        accountId: currentAccount.accountId,
+        relayId: currentAccount.relayId,
+        subscribeSessionIds,
+      });
+      ws = await connectRelaySocket({
+        account: currentAccount,
+        relayId: currentAccount.relayId,
+        subscribeSessionIds,
+      });
+      setRelaySocketConnected({
+        account: currentAccount,
+        ws,
+        relayId: currentAccount.relayId,
+        subscribeSessionIds,
+      });
+      monitorLog.info(
+        subscribeSessionIds && subscribeSessionIds.length > 0
+          ? `[${currentAccount.accountId}] sider relay connected (session subscriptions: ${subscribeSessionIds.join(", ")})`
+          : `[${currentAccount.accountId}] sider relay connected`,
+        {
+          accountId: currentAccount.accountId,
+          relayId: currentAccount.relayId,
+          subscribeSessionIds,
+        },
+      );
+
+      await new Promise<void>((resolve) => {
+        const socket = ws;
+        if (!socket) {
+          resolve();
+          return;
+        }
+        let settled = false;
+        let pendingPingSince = 0;
+
+        const finish = (params: {
+          reason: string;
+          closeSocket?: boolean;
+          logMessage?: string;
+          warn?: boolean;
+        }) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          if (params.logMessage) {
+            const data = {
+              accountId: currentAccount.accountId,
+              relayId: currentAccount.relayId,
+            };
+            const writeLog = params.warn ? monitorLog.warn : monitorLog.info;
+            writeLog(params.logMessage, data);
+          }
+          if (params.closeSocket) {
+            closeSocketQuietly(socket);
+          }
+          cleanup();
+          clearRelaySocketState({
+            accountId: currentAccount.accountId,
+            expectedWs: socket,
+            closeSocket: false,
+            reason: params.reason,
+          });
+          resolve();
+        };
+
+        const keepalive = setInterval(() => {
+          if (socket.readyState !== WebSocket.OPEN) {
+            return;
+          }
+          const now = Date.now();
+          if (pendingPingSince > 0 && now - pendingPingSince >= DEFAULT_MONITOR_PONG_TIMEOUT_MS) {
+            finish({
+              reason: `relay keepalive timeout after ${DEFAULT_MONITOR_PONG_TIMEOUT_MS}ms`,
+              closeSocket: true,
+              logMessage: `[${currentAccount.accountId}] sider relay keepalive timeout; reconnecting`,
+              warn: true,
+            });
+            return;
+          }
+          try {
+            socket.send(JSON.stringify({ type: "ping" }));
+            if (pendingPingSince === 0) {
+              pendingPingSince = now;
+            }
+            logDebug("sent sider relay keepalive ping", {
+              accountId: currentAccount.accountId,
+              relayId: currentAccount.relayId,
+              subscribeSessionIds,
+            });
+          } catch (err) {
+            monitorLog.warn(`[${currentAccount.accountId}] sider relay keepalive failed: ${String(err)}`, {
+              accountId: currentAccount.accountId,
+              relayId: currentAccount.relayId,
+              error: String(err),
+            });
+            closeSocketQuietly(socket);
+          }
+        }, DEFAULT_MONITOR_KEEPALIVE_MS);
+
+        const cleanup = () => {
+          clearInterval(keepalive);
+          socket.removeEventListener("message", onMessage);
+          socket.removeEventListener("close", onClose);
+          socket.removeEventListener("error", onError);
+          abortSignal.removeEventListener("abort", onAbort);
+        };
+
+        const onMessage = (event: MessageEvent) => {
+          void (async () => {
+            const text = await wsDataToText(event.data);
+            const frame = parseInboundFrame(text);
+            if (!frame) {
+              return;
+            }
+            if (frame.type === "event") {
+              return;
+            }
+            pendingPingSince = 0;
+            const frameRecord = toRecord(frame);
+            monitorLog.info("ws frame message", {
+              type: frame.type,
+              sessionId: typeof frameRecord?.session_id === "string" ? frameRecord.session_id : undefined,
+              messageId: typeof frameRecord?.message_id === "string" ? frameRecord.message_id : undefined,
+              eventId: typeof frameRecord?.event_id === "string" ? frameRecord.event_id : undefined,
+            });
+            if (frame.type === "ping") {
+              socket.send(JSON.stringify({ type: "pong" }));
+              return;
+            }
+            if (frame.type === "pong") {
+              logDebug("received sider relay keepalive pong", {
+                accountId: currentAccount.accountId,
+                relayId: currentAccount.relayId,
+              });
+              return;
+            }
+            if (frame.type === "replaced") {
+              monitorLog.warn(`[${currentAccount.accountId}] sider relay replaced by a newer connection`, {
+                accountId: currentAccount.accountId,
+                relayId: currentAccount.relayId,
+              });
+              closeSocketQuietly(socket);
+              return;
+            }
+            if (frame.type === "ack") {
+              const ackFrame = frame as SiderInboundAck;
+              const resolved = resolveManagedAck({
+                accountId: currentAccount.accountId,
+                frame: ackFrame,
+              });
+              logDebug("received sider ack on monitor socket", {
+                accountId: currentAccount.accountId,
+                sessionId: resolveAckSessionId(ackFrame),
+                id: resolveAckId(ackFrame),
+                clientReqId: resolveAckClientReqId(ackFrame),
+                resolved,
+              });
+              return;
+            }
+            if (frame.type !== "message") {
+              return;
+            }
+            await handleInboundRealtimeMessage({
+              cfg: currentCfg,
+              account: currentAccount,
+              event: frame,
+            });
+          })().catch((err) => {
+            log?.error(`[${currentAccount.accountId}] sider inbound handling failed: ${String(err)}`);
+          });
+        };
+
+        const onClose = (event: Event) => {
+          const closeInfo = getSocketCloseInfo(event);
+          if (closeInfo.code === 1008 && closeInfo.reason === "relay replaced") {
+            finish({
+              reason: `relay socket closed${describeSocketClose(event)}`,
+              logMessage: `[${currentAccount.accountId}] sider relay closed by gateway: relay replaced`,
+              warn: true,
+            });
+          } else {
+            finish({
+              reason: `relay socket closed${describeSocketClose(event)}`,
+              logMessage: `[${currentAccount.accountId}] sider relay socket closed${describeSocketClose(event)}`,
+            });
+          }
+        };
+        const onError = () => {
+          finish({
+            reason: "relay socket error",
+            logMessage: `[${currentAccount.accountId}] sider relay socket error`,
+            warn: true,
+          });
+        };
+        const onAbort = () => {
+          finish({
+            reason: "relay monitor aborted",
+            closeSocket: true,
+          });
+        };
+
+        socket.addEventListener("message", onMessage);
+        socket.addEventListener("close", onClose);
+        socket.addEventListener("error", onError);
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+
+        if (abortSignal.aborted) {
+          onAbort();
+        }
+      });
+    } catch (err) {
+      monitorLog.warn(`[${currentAccount.accountId}] sider relay loop error: ${String(err)}`, {
+        accountId: currentAccount.accountId,
+        relayId: currentAccount.relayId,
+        error: String(err),
+      });
+    } finally {
+      if (ws) {
+        clearRelaySocketState({
+          accountId: currentAccount.accountId,
+          expectedWs: ws,
+          closeSocket: false,
+          reason: "relay reconnecting",
+        });
+        closeSocketQuietly(ws);
+      }
+    }
+
+    if (!abortSignal.aborted && !skipSleep) {
+      await sleep(currentAccount.reconnectDelayMs);
+    }
+  }
+  clearRelaySocketState({
+    accountId: currentAccount.accountId,
+    closeSocket: true,
+  });
+}
+
+function launchManagedRelayMonitor(registration: SiderRelayMonitorRegistration): void {
+  const controller = new AbortController();
+  registration.controller = controller;
+  const runCfg = registration.cfg;
+  const runAccount = registration.account;
+  const runLog = registration.log;
+  registration.runner = (async () => {
+    try {
+      await monitorSiderSession({
+        cfg: runCfg,
+        account: runAccount,
+        abortSignal: controller.signal,
+        log: runLog,
+      });
+    } finally {
+      const current = siderRelayMonitors.get(runAccount.accountId);
+      if (current !== registration || current.controller !== controller) {
+        return;
+      }
+      if (current.restartRequested && current.subscribers.size > 0) {
+        current.restartRequested = false;
+        launchManagedRelayMonitor(current);
+        return;
+      }
+      if (current.subscribers.size > 0) {
+        current.log?.warn(
+          `[${current.account.accountId}] managed sider relay monitor stopped unexpectedly; restarting`,
+        );
+        launchManagedRelayMonitor(current);
+        return;
+      }
+      siderRelayMonitors.delete(runAccount.accountId);
+    }
+  })();
+}
+
+async function runManagedSiderRelayMonitor(params: {
+  cfg: OpenClawConfig;
+  account: ResolvedSiderAccount;
+  abortSignal: AbortSignal;
+  log?: SiderMonitorLogger;
+}): Promise<void> {
+  const { account, abortSignal, log } = params;
+  const subscriberId = crypto.randomUUID();
+  const monitorSignature = buildRelayMonitorAccountSignature(account);
+  let registration = siderRelayMonitors.get(account.accountId);
+
+  if (!registration) {
+    registration = {
+      cfg: params.cfg,
+      account,
+      monitorSignature,
+      subscribers: new Set([subscriberId]),
+      controller: new AbortController(),
+      runner: Promise.resolve(),
+      restartRequested: false,
+      log,
+    };
+    siderRelayMonitors.set(account.accountId, registration);
+    launchManagedRelayMonitor(registration);
+  } else {
+    registration.subscribers.add(subscriberId);
+    registration.log = log ?? registration.log;
+    if (registration.monitorSignature !== monitorSignature) {
+      registration.cfg = params.cfg;
+      registration.account = account;
+      registration.monitorSignature = monitorSignature;
+      registration.restartRequested = true;
+      log?.info(`[${account.accountId}] restarting sider relay monitor with updated settings`);
+      registration.controller.abort();
+    } else {
+      log?.info(`[${account.accountId}] reusing existing sider relay monitor`);
+    }
+  }
+
+  try {
+    await waitForAbortSignal(abortSignal);
+  } finally {
+    const current = siderRelayMonitors.get(account.accountId);
+    if (!current) {
+      return;
+    }
+    current.subscribers.delete(subscriberId);
+    if (current.subscribers.size > 0) {
+      return;
+    }
+    current.controller.abort();
+    await current.runner;
+  }
+}
+
+export const siderPlugin: ChannelPlugin<ResolvedSiderAccount> = {
+  id: SIDER_CHANNEL_ID,
+  meta,
+  setupWizard: siderSetupWizard,
+  setup: siderSetupAdapter,
+  capabilities: {
+    chatTypes: ["direct"],
+    threads: false,
+    media: true,
+    blockStreaming: true,
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "- Sider targeting: omit `to` to reply in the current conversation (auto-inferred).",
+      "- To send an image or file to the current user, use the message tool with action='send' and set 'media' to a local file path or a remote HTTPS URL. You do not need to specify 'to' — the current conversation recipient is used automatically.",
+      "- When the user asks you to find an image from the web, use a web search or browser tool to find a suitable image URL, then send it using the message tool with 'media' set to that HTTPS image URL — do NOT download the image first.",
+      "- IMPORTANT: When generating or saving a file to send, always use an absolute path (e.g. /tmp/photo.png), never a relative path like ./photo.png. Relative paths cannot be resolved and the file will not be delivered.",
+      "- For `sessions_send`, use OpenClaw session keys (for example `sessions_list[].key`), not provider conversation ids like `01K...`.",
+    ],
+  },
+  streaming: {
+    blockStreamingCoalesceDefaults: { minChars: 1200, idleMs: 900 },
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean" },
+        name: { type: "string" },
+        setupToken: { type: "string" },
+        sessionId: { type: "string" },
+        subscribeSessionIds: {
+          type: "array",
+          items: { type: "string" },
+        },
+        relayId: { type: "string" },
+        token: { type: "string" },
+        defaultTo: { type: "string" },
+        connectTimeoutMs: { type: "number", minimum: 1 },
+        sendTimeoutMs: { type: "number", minimum: 1 },
+        reconnectDelayMs: { type: "number", minimum: 1 },
+        accounts: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              enabled: { type: "boolean" },
+              name: { type: "string" },
+              setupToken: { type: "string" },
+              sessionId: { type: "string" },
+              subscribeSessionIds: {
+                type: "array",
+                items: { type: "string" },
+              },
+              relayId: { type: "string" },
+              token: { type: "string" },
+              defaultTo: { type: "string" },
+              connectTimeoutMs: { type: "number", minimum: 1 },
+              sendTimeoutMs: { type: "number", minimum: 1 },
+              reconnectDelayMs: { type: "number", minimum: 1 },
+            },
+          },
+        },
+      },
+    },
+  },
+  reload: { configPrefixes: [`channels.${SIDER_CHANNEL_ID}`] },
+  config: {
+    listAccountIds: (cfg) => listSiderAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveSiderAccount(cfg, accountId),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    isConfigured: (account) => account.configured || isSiderAccountBootstrappable(account),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+      name: account.name,
+      baseUrl: account.gatewayUrl,
+      relayId: account.relayId,
+      sessionId: account.sessionId,
+      subscribeSessionIds: account.subscribeSessionIds,
+    }),
+    resolveDefaultTo: ({ cfg, accountId }) => resolveSiderAccount(cfg, accountId).defaultTo,
+  },
+  actions: {
+    describeMessageTool: ({ cfg }) => {
+      const hasConfigured = listSiderAccountIds(cfg).some(
+        (accountId) => {
+          const account = resolveSiderAccount(cfg, accountId);
+          return account.configured || isSiderAccountBootstrappable(account);
+        },
+      );
+      return hasConfigured ? { actions: ["sendAttachment", "send"] as const } : null;
+    },
+    supportsAction: ({ action }) => action === "sendAttachment" || action === "send",
+    extractToolSend: ({ args }) => extractSiderToolSend(args),
+    handleAction: async ({ action, params, cfg, accountId, mediaLocalRoots }) => {
+      if (action === "send") {
+        const account = await resolveManagedSiderAccount({ cfg, accountId });
+        if (!account.configured) {
+          throw new Error(describeSiderAccountConfigurationError(account));
+        }
+        const to = readStringParam(params, "to", { required: true });
+        const mediaUrl =
+          readStringParam(params, "media", { trim: false }) ??
+          readStringParam(params, "mediaUrl", { trim: false }) ??
+          readStringParam(params, "path", { trim: false }) ??
+          readStringParam(params, "filePath", { trim: false });
+        const text =
+          readStringParam(params, "message", { allowEmpty: true }) ??
+          readStringParam(params, "caption", { allowEmpty: true }) ??
+          undefined;
+        const sessionId = resolveOutboundSessionId({ account, to });
+        const parts = await buildSiderPartsFromReplyPayload({
+          account,
+          sessionId,
+          payload: {
+            text,
+            mediaUrl: mediaUrl ?? undefined,
+          },
+          mediaLocalRoots,
+          logger: {
+            debug: logDebug,
+            warn: logWarn,
+          },
+        });
+        if (parts.length === 0) {
+          throw new Error("sider send requires text or media");
+        }
+        const result = await sendMessageToSider({
+          account,
+          sessionId,
+          parts,
+        });
+        return jsonResult({
+          ok: true,
+          channel: SIDER_CHANNEL_ID,
+          messageId: result.messageId,
+          conversationId: result.conversationId,
+        });
+      }
+      if (action !== "sendAttachment") {
+        throw new Error(`sider action ${action} is not supported`);
+      }
+      const account = await resolveManagedSiderAccount({ cfg, accountId });
+      if (!account.configured) {
+        throw new Error(describeSiderAccountConfigurationError(account));
+      }
+      const to = readStringParam(params, "to", { required: true });
+      const rawBuffer = readStringParam(params, "buffer", { trim: false, required: true });
+      const contentType =
+        readStringParam(params, "contentType", { trim: false }) ??
+        readStringParam(params, "mimeType", { trim: false });
+      const fileName = readStringParam(params, "filename", { trim: false }) ?? undefined;
+      const text =
+        readStringParam(params, "caption", { allowEmpty: true }) ??
+        readStringParam(params, "message", { allowEmpty: true }) ??
+        undefined;
+      const sessionId = resolveOutboundSessionId({ account, to });
+      const buffer = decodeBase64AttachmentBuffer(rawBuffer);
+      const savedAttachment = await persistInlineAttachmentBuffer({
+        cfg,
+        accountId,
+        buffer,
+        contentType: contentType ?? undefined,
+        fileName,
+      });
+      const resolvedContentType = contentType ?? savedAttachment.contentType ?? undefined;
+      const resolvedFileName = fileName ?? savedAttachment.path;
+      const parts: SiderPart[] = [];
+      const trimmedText = text?.trim();
+      if (trimmedText) {
+        parts.push({
+          type: "core.text",
+          spec_version: 1,
+          payload: { text: trimmedText },
+        });
+      }
+      parts.push(
+        await buildSiderPartFromInlineAttachment({
+          account,
+          sessionId,
+          buffer,
+          contentType: resolvedContentType,
+          fileName: resolvedFileName,
+          sourceLabel: resolvedFileName,
+          logger: {
+            debug: logDebug,
+            warn: logWarn,
+          },
+        }),
+      );
+      const result = await sendMessageToSider({
+        account,
+        sessionId,
+        parts,
+      });
+      return jsonResult({
+        ok: true,
+        channel: SIDER_CHANNEL_ID,
+        messageId: result.messageId,
+        conversationId: result.conversationId,
+        path: savedAttachment.path,
+        mediaUrl: savedAttachment.path,
+        mediaUrls: [savedAttachment.path],
+        contentType: resolvedContentType,
+        filename: resolvedFileName,
+      });
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async ({ cfg, accountId, to, text, mediaLocalRoots }) => {
+      const account = await resolveManagedSiderAccount({ cfg, accountId });
+      if (!account.configured) {
+        throw new Error(describeSiderAccountConfigurationError(account));
+      }
+      const sessionId = resolveOutboundSessionId({ account, to });
+      const parts = await buildSiderPartsFromReplyPayload({
+        account,
+        sessionId,
+        payload: {
+          text,
+        },
+        mediaLocalRoots,
+        logger: {
+          debug: logDebug,
+          warn: logWarn,
+        },
+      });
+      if (parts.length === 0) {
+        throw new Error("sider sendText requires non-empty text or uploadable media reference");
+      }
+      const result = await sendMessageToSider({
+        account,
+        sessionId,
+        parts,
+      });
+      return {
+        channel: SIDER_CHANNEL_ID,
+        messageId: result.messageId,
+        conversationId: result.conversationId,
+      };
+    },
+    sendMedia: async ({ cfg, accountId, to, text, mediaUrl, mediaLocalRoots }) => {
+      const account = await resolveManagedSiderAccount({ cfg, accountId });
+      if (!account.configured) {
+        throw new Error(describeSiderAccountConfigurationError(account));
+      }
+      const sessionId = resolveOutboundSessionId({ account, to });
+      const parts = await buildSiderPartsFromReplyPayload({
+        account,
+        sessionId,
+        payload: {
+          text,
+          mediaUrl,
+        },
+        mediaLocalRoots,
+        logger: {
+          debug: logDebug,
+          warn: logWarn,
+        },
+      });
+      if (parts.length === 0) {
+        throw new Error("sider sendMedia requires text and/or mediaUrl");
+      }
+      const result = await sendMessageToSider({
+        account,
+        sessionId,
+        parts,
+      });
+      return {
+        channel: SIDER_CHANNEL_ID,
+        messageId: result.messageId,
+        conversationId: result.conversationId,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = await resolveManagedSiderAccount({
+        cfg: ctx.cfg,
+        accountId: ctx.accountId,
+      });
+      if (!account.configured) {
+        throw new Error(describeSiderAccountConfigurationError(account));
+      }
+      ctx.log?.info(
+        `[${account.accountId}] starting sider relay monitor (${account.gatewayUrl}, relayId=${account.relayId})`,
+      );
+      await runManagedSiderRelayMonitor({
+        cfg: ctx.cfg,
+        account,
+        abortSignal: ctx.abortSignal,
+        log: ctx.log,
+      });
+      ctx.log?.info(`[${account.accountId}] sider relay monitor watcher stopped`);
+    },
+  },
+  auth: {
+    login: async ({ accountId, runtime }) => {
+      const resolvedAccountId = normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID;
+      for (;;) {
+        const pairing = await requestSiderPairing();
+        runtime.log(
+          formatSiderPairingInstructions({
+            pairingCode: pairing.pairingCode,
+            leadLine: "One more step to connect:",
+          }),
+        );
+        const reportPendingUpdate = createSiderPairingPendingUpdateReporter({
+          pairingCode: pairing.pairingCode,
+          report: (message) => {
+            runtime.log(message);
+          },
+        });
+        try {
+          const paired = await waitForSiderPairing({
+            pairing,
+            onPending: reportPendingUpdate,
+            onRetryableError: (message) => {
+              runtime.log(message);
+            },
+          });
+          const latestCfg = loadConfig();
+          const nextCfg = applySiderSetupAccountConfig({
+            cfg: latestCfg,
+            accountId: resolvedAccountId,
+            input: {
+              token: paired.token,
+            },
+          });
+          await writeConfigFile(nextCfg);
+          runtime.log("Connected! You can now chat with me in the browser Side Panel.");
+          return;
+        } catch (error) {
+          if (error instanceof SiderPairingExpiredError) {
+            runtime.log("Pairing code expired.");
+            runtime.log("Generating a new code...");
+            continue;
+          }
+          throw error;
+        }
+      }
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeSiderMessagingTarget,
+    targetResolver: {
+      looksLikeId: looksLikeSiderTargetId,
+      hint: "session:<sessionId> (or raw <sessionId>)",
+    },
+  },
+};