@workclaw/openclaw-workchat 1.0.0 → 1.0.3

package/src/messaging/process-message.ts

@@ -1,530 +1,530 @@
-import {
-  resolveSenderCommandAuthorizationWithRuntime,
-  resolveDirectDmAuthorizationOutcome,
-} from "openclaw/plugin-sdk/command-auth";
-import type { PluginRuntime } from "openclaw/plugin-sdk";
-
-import { notifyAgentCreatedStatus } from "../api/api.js";
-import type { WorkChatApiOptions } from "../api/api.js";
-import {
-  listIndexedWorkChatAccountIds,
-  loadWorkChatAccount,
-  registerWorkChatAccountId,
-  saveWorkChatAccount,
-  triggerWorkChatChannelReload,
-  pruneStaleWorkChatAccounts,
-  removeWorkChatAccountBinding,
-} from "../auth/accounts.js";
-import type { ResolvedWorkChatAccount } from "../auth/accounts.js";
-import { readFrameworkAllowFromList } from "../auth/pairing.js";
-import { logger } from "../util/logger.js";
-import { redactBody } from "../util/redact.js";
-
-import { isDebugMode } from "./debug-mode.js";
-import { sendWorkChatErrorNotice } from "./error-notice.js";
-import type { ParseWorkChatFrameResult } from "./inbound.js";
-import { workChatMessageToMsgContext } from "./inbound.js";
-import { handleSlashCommand } from "./slash-commands.js";
-
-// workchat_lazy_outbound_hooks: hooks are not needed for registration or QR binding.
-let workchatOutboundHooksPromise: Promise<typeof import("./outbound-hooks.js")> | null = null;
-function loadWorkChatOutboundHooks() {
-  workchatOutboundHooksPromise ??= import("./outbound-hooks.js");
-  return workchatOutboundHooksPromise;
-}
-
-async function applyWorkChatMessageSendingHook(params: {
-  to: string;
-  text: string;
-  accountId?: string;
-}): Promise<{ cancelled: boolean; text: string }> {
-  try {
-    const hooks = await loadWorkChatOutboundHooks();
-    return hooks.applyWorkChatMessageSendingHook(params);
-  } catch (error) {
-    logger.warn(`message_sending hook load error, proceeding with send: ${String(error)}`);
-    return { cancelled: false, text: params.text };
-  }
-}
-
-function emitWorkChatMessageSent(params: {
-  to: string;
-  content: string;
-  success: boolean;
-  error?: string;
-  accountId?: string;
-}): void {
-  void loadWorkChatOutboundHooks()
-    .then((hooks) => hooks.emitWorkChatMessageSent(params))
-    .catch((error) => logger.warn(`message_sent hook load error: ${String(error)}`));
-}
-
-/** Dependencies for processOneFrame, injected by the monitor loop. */
-export type ProcessFrameDeps = {
-  accountId: string;
-  account: ResolvedWorkChatAccount;
-  config: import("openclaw/plugin-sdk").OpenClawConfig;
-  channelRuntime: PluginRuntime["channel"];
-  apiOpts: WorkChatApiOptions;
-  log: (msg: string) => void;
-  errLog: (m: string) => void;
-};
-
-/** Persist agent/user ids discovered from AGENT_CREATED / INIT_AGENT events. */
-async function handleAgentLifecycleEvent(
-  frameType: "agent_created" | "init_agent",
-  result: ParseWorkChatFrameResult,
-  deps: ProcessFrameDeps,
-): Promise<void> {
-  const eventData = result.eventData;
-  if (!eventData) return;
-
-  const agentId = String(eventData.id ?? eventData.agentId ?? "");
-  if (!agentId) {
-    logger.warn(`${frameType}: missing agent id, ignoring`);
-    return;
-  }
-  const userId = String(eventData.futureId ?? eventData.userId ?? "");
-
-  logger.info(`${frameType}: agentId=${agentId} userId=${userId ? "present" : "missing"}`);
-  deps.log(`${frameType}: agentId=${agentId}`);
-
-  // Rebind detection must happen BEFORE pruning empties the index (see the
-  // matching note in the binding listener): a rebind always registers under a
-  // FRESH agent-scoped key so the gateway restarts it — the QR login flow
-  // force-stops the channel with a manual-stop mark, and a reused account id
-  // would stay stopped after the config reload.
-  const isRebind = listWorkChatAccountIdsCount() > 0;
-
-  // Rebind semantics: one active agent per host. Before persisting the new
-  // binding, remove every registered account bound to a different agent
-  // (a re-scan creates a new platform agent; the old one is deleted there).
-  try {
-    const removed = await pruneStaleWorkChatAccounts(agentId);
-    if (removed.length > 0) {
-      deps.log(`rebind: removed stale account(s): ${removed.join(", ")}`);
-    }
-  } catch (err) {
-    logger.error(`rebind cleanup failed: ${String(err)}`);
-  }
-
-  // The bound agent becomes the account: `default` for the primary install,
-  // or a fresh agent-scoped key on rebind.
-  const { completeWorkChatBinding } = await import("../auth/login-qr.js");
-  const accountId = frameType === "init_agent"
-    ? (isRebind ? `agent-${agentId}` : "default")
-    : deps.accountId;
-
-  try {
-    saveWorkChatAccount(accountId, {
-      agentId,
-      ...(userId ? { userId } : {}),
-    });
-    registerWorkChatAccountId(accountId);
-    // Bind the account to the incoming agent for message routing. agentId
-    // comes from the event; userId (futureId) is the WorkChat user.
-    const { bindAgentToAccount } = await import("../auth/bind-agent.js");
-    await bindAgentToAccount(accountId, agentId, userId);
-    logger.info(`${frameType}: bound agent to account accountId=${accountId}`);
-    await triggerWorkChatChannelReload();
-  } catch (err) {
-    logger.error(`${frameType}: failed to save account data err=${String(err)}`);
-  }
-
-  // INIT_AGENT closes the pending QR binding session (if any).
-  if (frameType === "init_agent") {
-    const resolved = completeWorkChatBinding({
-      accountId,
-      agentId,
-      ...(userId ? { userId } : {}),
-    });
-    if (resolved) {
-      deps.log(`绑定完成: agentId=${agentId}`);
-    }
-  }
-
-  if (frameType === "agent_created") {
-    // Ack the platform that the local side is ready (best-effort, non-fatal).
-    void notifyAgentCreatedStatus(deps.apiOpts, agentId);
-  }
-}
-
-function listWorkChatAccountIdsCount(): number {
-  return listIndexedWorkChatAccountIds().length;
-}
-
-// Typing-indicator helper versions: the host renamed the subpath between
-// releases (2026.3.x exports openclaw/plugin-sdk/channel-runtime, 2026.8.x
-// exports openclaw/plugin-sdk/channel-message). Load whichever resolves —
-// both export createTypingCallbacks. WorkChat has no typing API, so the
-// callbacks are no-op; only the dispatcher lifecycle shape matters.
-let createTypingCallbacksPromise: Promise<((opts: unknown) => unknown) | null> | undefined;
-function loadCreateTypingCallbacks(): Promise<((opts: unknown) => unknown) | null> {
-  createTypingCallbacksPromise ??= (async () => {
-    for (const specifier of ["openclaw/plugin-sdk/channel-runtime", "openclaw/plugin-sdk/channel-message"]) {
-      try {
-        // Variable specifier keeps the import dynamic so both host versions
-        // resolve at runtime instead of one failing at bundle time.
-        const mod = (await import(specifier)) as { createTypingCallbacks?: (opts: unknown) => unknown };
-        if (typeof mod?.createTypingCallbacks === "function") return mod.createTypingCallbacks;
-      } catch {
-        // subpath not present on this host — try the next
-      }
-    }
-    return null;
-  })();
-  return createTypingCallbacksPromise;
-}
-
-async function createNoopTypingCallbacks(): Promise<unknown> {
-  const createTypingCallbacks = await loadCreateTypingCallbacks();
-  if (!createTypingCallbacks) {
-    // Host exposes neither subpath: minimal lifecycle stub.
-    return { start: () => {}, stop: () => {} };
-  }
-  return createTypingCallbacks({
-    start: async () => {},
-    stop: async () => {},
-    onStartError: () => {},
-    onStopError: () => {},
-    keepaliveIntervalMs: 5000,
-  });
-}
-
-
-
-/**
- * Process a single parsed inbound frame: lifecycle events are persisted,
- * AGENT_MESSAGE frames are authorized, routed, and dispatched into the core
- * reply pipeline.
- */
-export async function processOneFrame(
-  result: ParseWorkChatFrameResult,
-  rawFrame: string,
-  deps: ProcessFrameDeps,
-): Promise<void> {
-  if (!deps?.channelRuntime) {
-    logger.error(`processOneFrame: channelRuntime is undefined, skipping type=${result.type}`);
-    return;
-  }
-
-  switch (result.type) {
-    case "agent_created":
-    case "init_agent":
-      await handleAgentLifecycleEvent(result.type, result, deps);
-      return;
-    case "agent_updated":
-      logger.info(`${result.type}: no local action`);
-      return;
-    case "agent_deleted": {
-      // The platform deleted this agent (e.g. a re-scan replaced it): tear
-      // down the local account binding so no dead monitor keeps running.
-      const eventData = result.eventData;
-      const deletedAgentId = String(eventData?.id ?? eventData?.agentId ?? "").trim();
-      if (!deletedAgentId) {
-        logger.warn("agent_deleted: missing agent id, ignoring");
-        return;
-      }
-      const victim = listIndexedWorkChatAccountIds()
-        .find(id => loadWorkChatAccount(id)?.agentId?.trim() === deletedAgentId);
-      if (victim) {
-        try {
-          await removeWorkChatAccountBinding(victim);
-          await triggerWorkChatChannelReload();
-          deps.log(`agent_deleted: removed account=${victim} agent=${deletedAgentId}`);
-        } catch (err) {
-          logger.error(`agent_deleted: failed to remove account=${victim}: ${String(err)}`);
-        }
-      } else {
-        logger.info(`agent_deleted: agent=${deletedAgentId} not bound locally, ignoring`);
-      }
-      return;
-    }
-    case "ignored":
-      // Unhandled-but-recognized frames (TOOLS_LIST/SKILLS_LIST/SKILL_DO_REMIND/
-      // CRON_REMIND...): log the raw kind so platform pushes are observable.
-      logger.debug(`ignored frame kind=${result.ignoredKind ?? "(unknown)"}`);
-      return;
-    case "ping":
-    case "disconnect":
-      return;
-    case "agent_message":
-      break;
-    default:
-      return;
-  }
-
-  const message = result.message;
-  if (!message) return;
-  if (!message.text?.trim()) {
-    logger.debug("inbound: empty body, ignoring");
-    return;
-  }
-
-  const receivedAt = Date.now();
-  const debug = isDebugMode(deps.accountId);
-  const debugTrace: string[] = [];
-  const debugTs: Record<string, number> = { received: receivedAt };
-
-  const ctx = workChatMessageToMsgContext(message, deps.accountId);
-  logger.info(
-    `inbound: from=${ctx.From} to=${ctx.To} bodyLen=${ctx.Body.length} conversationId=${ctx.ConversationId ?? "(none)"}`,
-  );
-  logger.debug(`inbound raw frame: ${rawFrame.slice(0, 200)}`);
-
-  // --- Slash commands (handled locally, never dispatched to AI) ---
-  if (ctx.Body.trim().startsWith("/")) {
-    const slashResult = await handleSlashCommand(ctx.Body, {
-      account: deps.account,
-      to: ctx.To,
-      agentId: ctx.AgentId,
-      log: deps.log,
-      errLog: deps.errLog,
-    }, receivedAt);
-    if (slashResult.handled) {
-      return;
-    }
-  }
-
-  // --- Framework command authorization ---
-  const rawBody = ctx.Body?.trim() ?? "";
-  ctx.CommandBody = rawBody;
-  const senderId = ctx.From;
-
-  const { senderAllowedForCommands, commandAuthorized } =
-    await resolveSenderCommandAuthorizationWithRuntime({
-      cfg: deps.config,
-      rawBody,
-      isGroup: false,
-      dmPolicy: "pairing",
-      configuredAllowFrom: [],
-      configuredGroupAllowFrom: [],
-      senderId,
-      isSenderAllowed: (id: string, list: string[]) => list.length === 0 || list.includes(id),
-      /** Pairing: framework credentials `*-allowFrom.json`, with account `userId` fallback for legacy installs. */
-      readAllowFromStore: async () => {
-        const fromStore = readFrameworkAllowFromList(deps.accountId);
-        if (fromStore.length > 0) return fromStore;
-        const uid = loadWorkChatAccount(deps.accountId)?.userId?.trim();
-        return uid ? [uid] : [];
-      },
-      runtime: deps.channelRuntime.commands,
-    });
-
-  const directDmOutcome = resolveDirectDmAuthorizationOutcome({
-    isGroup: false,
-    dmPolicy: "pairing",
-    senderAllowedForCommands,
-  });
-
-  if (directDmOutcome === "disabled" || directDmOutcome === "unauthorized") {
-    logger.info(
-      `authorization: dropping message from=${senderId} outcome=${directDmOutcome}`,
-    );
-    return;
-  }
-
-  ctx.CommandAuthorized = commandAuthorized;
-  logger.debug(
-    `authorization: senderId=${senderId} commandAuthorized=${String(commandAuthorized)} senderAllowed=${String(senderAllowedForCommands)}`,
-  );
-
-  if (debug) {
-    debugTrace.push(
-      "── 鉴权 & 路由 ──",
-      `│ auth: cmdAuthorized=${String(commandAuthorized)} senderAllowed=${String(senderAllowedForCommands)}`,
-    );
-  }
-
-  const route = deps.channelRuntime.routing.resolveAgentRoute({
-    cfg: deps.config,
-    channel: "openclaw-workchat",
-    accountId: deps.accountId,
-    peer: { kind: "direct", id: ctx.To },
-  });
-  logger.debug(
-    `resolveAgentRoute: agentId=${route.agentId ?? "(none)"} sessionKey=${route.sessionKey ?? "(none)"} mainSessionKey=${route.mainSessionKey ?? "(none)"}`,
-  );
-  if (!route.agentId) {
-    logger.error(
-      `resolveAgentRoute: no agentId resolved for peer=${ctx.To} accountId=${deps.accountId} — message will not be dispatched`,
-    );
-  }
-
-  if (debug) {
-    debugTrace.push(`│ route: agent=${route.agentId ?? "none"} session=${route.sessionKey ?? "none"}`);
-    debugTs.preDispatch = Date.now();
-  }
-  // Propagate the resolved session key into ctx so dispatchReplyFromConfig uses
-  // the correct session (matching the dmScope from config) instead of falling back.
-  ctx.SessionKey = route.sessionKey;
-  const storePath = deps.channelRuntime.session.resolveStorePath(deps.config.session?.store, {
-    agentId: route.agentId,
-  });
-  const finalized = deps.channelRuntime.reply.finalizeInboundContext(
-    ctx as Parameters<typeof deps.channelRuntime.reply.finalizeInboundContext>[0],
-  );
-
-  logger.info(
-    `inbound: from=${finalized.From} to=${finalized.To} bodyLen=${(finalized.Body ?? "").length}`,
-  );
-  logger.debug(`inbound context: ${redactBody(JSON.stringify(finalized))}`);
-
-  await deps.channelRuntime.session.recordInboundSession({
-    storePath,
-    sessionKey: route.sessionKey,
-    ctx: finalized as Parameters<typeof deps.channelRuntime.session.recordInboundSession>[0]["ctx"],
-    updateLastRoute: {
-      sessionKey: route.mainSessionKey,
-      channel: "openclaw-workchat",
-      to: ctx.To,
-      accountId: deps.accountId,
-    },
-    onRecordError: (err) => deps.errLog(`recordInboundSession: ${String(err)}`),
-  });
-  logger.debug(`recordInboundSession: done storePath=${storePath} sessionKey=${route.sessionKey ?? "(none)"}`);
-
-  const humanDelay = deps.channelRuntime.reply.resolveHumanDelayConfig(deps.config, route.agentId);
-
-  const typingCallbacks = await createNoopTypingCallbacks();
-
-  /** Delivery records populated synchronously at deliver() entry, safe to read in finally. */
-  const debugDeliveries: Array<{ textLen: number; preview: string; ts: number }> = [];
-
-  const { dispatcher, replyOptions, markDispatchIdle } =
-    deps.channelRuntime.reply.createReplyDispatcherWithTyping({
-      humanDelay,
-      // Shape comes from a host-version-dependent loader; the local SDK's
-      // TypingCallbacks type does not apply cleanly across versions.
-      typingCallbacks: typingCallbacks as any,
-      deliver: async (payload) => {
-        // Lazy-load send + markdown filter to keep registration / QR binding import-light.
-        const [{ replyWorkChatMessage }, { StreamingMarkdownFilter }] = await Promise.all([
-          import("./send.js"),
-          import("./markdown-filter.js"),
-        ]);
-        const rawText = String(payload.text ?? "");
-        const f = new StreamingMarkdownFilter();
-        let text = f.feed(rawText) + f.flush();
-
-        logger.info(`outbound: to=${ctx.To} textLen=${text.length}`);
-
-        if (debug) {
-          debugDeliveries.push({
-            textLen: text.length,
-            preview: `${text.slice(0, 60)}${text.length > 60 ? "…" : ""}`,
-            ts: Date.now(),
-          });
-        }
-
-        const sendingResult = await applyWorkChatMessageSendingHook({
-          to: ctx.To,
-          text,
-          accountId: deps.accountId,
-        });
-        if (sendingResult.cancelled) {
-          logger.info(`outbound: cancelled by message_sending hook to=${ctx.To}`);
-          return;
-        }
-        text = sendingResult.text;
-
-        try {
-          const result = await replyWorkChatMessage({
-            account: {
-              ...deps.account,
-              agentId: ctx.AgentId ?? deps.account.agentId,
-              userId: ctx.From || deps.account.userId,
-            },
-            to: ctx.To,
-            text,
-            replyToMessageId: ctx.MessageSid,
-            conversationId: ctx.ConversationId,
-            agentId: ctx.AgentId,
-            last: true,
-          });
-          emitWorkChatMessageSent({ to: ctx.To, content: text, success: true, accountId: deps.accountId });
-          logger.info(`outbound: reply sent OK to=${ctx.To} messageId=${result.messageId}`);
-        } catch (err) {
-          emitWorkChatMessageSent({ to: ctx.To, content: text, success: false, error: String(err), accountId: deps.accountId });
-          logger.error(`outbound: FAILED to=${ctx.To} err=${String(err)}`);
-          throw err;
-        }
-      },
-      onError: (err, info) => {
-        deps.errLog(`workchat reply ${info.kind}: ${String(err)}`);
-        const errMsg = err instanceof Error ? err.message : String(err);
-        const notice = `⚠️ 消息发送失败：${errMsg}`;
-        void sendWorkChatErrorNotice({
-          account: deps.account,
-          to: ctx.To,
-          message: notice,
-          agentId: ctx.AgentId,
-          errLog: deps.errLog,
-        });
-      },
-    });
-
-  logger.debug(`dispatchReplyFromConfig: starting agentId=${route.agentId ?? "(none)"}`);
-  try {
-    await deps.channelRuntime.reply.withReplyDispatcher({
-      dispatcher,
-      run: () =>
-        deps.channelRuntime.reply.dispatchReplyFromConfig({
-          ctx: finalized,
-          cfg: deps.config,
-          dispatcher,
-          replyOptions: { ...replyOptions, disableBlockStreaming: true },
-        }),
-    });
-    logger.debug(`dispatchReplyFromConfig: done agentId=${route.agentId ?? "(none)"}`);
-  } catch (err) {
-    logger.error(
-      `dispatchReplyFromConfig: error agentId=${route.agentId ?? "(none)"} err=${String(err)}`,
-    );
-    throw err;
-  } finally {
-    markDispatchIdle();
-
-    if (debug) {
-      const dispatchDoneAt = Date.now();
-      const inboundProcessMs = (debugTs.preDispatch ?? receivedAt) - receivedAt;
-      const aiMs = dispatchDoneAt - (debugTs.preDispatch ?? receivedAt);
-      const totalTime = dispatchDoneAt - receivedAt;
-
-      if (debugDeliveries.length > 0) {
-        debugTrace.push("── 回复 ──");
-        for (const d of debugDeliveries) {
-          debugTrace.push(`│ textLen=${d.textLen}`, `│ text="${d.preview}"`);
-        }
-        const firstTs = debugDeliveries[0].ts;
-        debugTrace.push(`│ deliver耗时: ${dispatchDoneAt - firstTs}ms`);
-      } else {
-        debugTrace.push("── 回复 ──", "│ (deliver未捕获)");
-      }
-
-      debugTrace.push(
-        "── 耗时 ──",
-        `├ 入站处理(auth+route): ${inboundProcessMs}ms`,
-        `├ AI生成+回复: ${aiMs}ms`,
-        `├ 总耗时: ${totalTime}ms`,
-      );
-
-      const timingText = `⏱ Debug 全链路\n${debugTrace.join("\n")}`;
-      logger.info(`debug-timing: sending to=${ctx.To}`);
-      void import("./send.js").then(({ pushWorkChatMessage }) =>
-        pushWorkChatMessage({
-          account: {
-            ...deps.account,
-            agentId: ctx.AgentId ?? deps.account.agentId,
-            userId: ctx.From || deps.account.userId,
-          },
-          to: ctx.To,
-          text: timingText,
-          agentId: ctx.AgentId,
-        }),
-      ).catch((debugErr) => {
-        logger.error(`debug-timing: send FAILED err=${String(debugErr)}`);
-      });
-    }
-  }
-}
+import {
+  resolveSenderCommandAuthorizationWithRuntime,
+  resolveDirectDmAuthorizationOutcome,
+} from "openclaw/plugin-sdk/command-auth";
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+import { notifyAgentCreatedStatus } from "../api/api.js";
+import type { WorkChatApiOptions } from "../api/api.js";
+import {
+  listIndexedWorkChatAccountIds,
+  loadWorkChatAccount,
+  registerWorkChatAccountId,
+  saveWorkChatAccount,
+  triggerWorkChatChannelReload,
+  pruneStaleWorkChatAccounts,
+  removeWorkChatAccountBinding,
+} from "../auth/accounts.js";
+import type { ResolvedWorkChatAccount } from "../auth/accounts.js";
+import { readFrameworkAllowFromList } from "../auth/pairing.js";
+import { logger } from "../util/logger.js";
+import { redactBody } from "../util/redact.js";
+
+import { isDebugMode } from "./debug-mode.js";
+import { sendWorkChatErrorNotice } from "./error-notice.js";
+import type { ParseWorkChatFrameResult } from "./inbound.js";
+import { workChatMessageToMsgContext } from "./inbound.js";
+import { handleSlashCommand } from "./slash-commands.js";
+
+// workchat_lazy_outbound_hooks: hooks are not needed for registration or QR binding.
+let workchatOutboundHooksPromise: Promise<typeof import("./outbound-hooks.js")> | null = null;
+function loadWorkChatOutboundHooks() {
+  workchatOutboundHooksPromise ??= import("./outbound-hooks.js");
+  return workchatOutboundHooksPromise;
+}
+
+async function applyWorkChatMessageSendingHook(params: {
+  to: string;
+  text: string;
+  accountId?: string;
+}): Promise<{ cancelled: boolean; text: string }> {
+  try {
+    const hooks = await loadWorkChatOutboundHooks();
+    return hooks.applyWorkChatMessageSendingHook(params);
+  } catch (error) {
+    logger.warn(`message_sending hook load error, proceeding with send: ${String(error)}`);
+    return { cancelled: false, text: params.text };
+  }
+}
+
+function emitWorkChatMessageSent(params: {
+  to: string;
+  content: string;
+  success: boolean;
+  error?: string;
+  accountId?: string;
+}): void {
+  void loadWorkChatOutboundHooks()
+    .then((hooks) => hooks.emitWorkChatMessageSent(params))
+    .catch((error) => logger.warn(`message_sent hook load error: ${String(error)}`));
+}
+
+/** Dependencies for processOneFrame, injected by the monitor loop. */
+export type ProcessFrameDeps = {
+  accountId: string;
+  account: ResolvedWorkChatAccount;
+  config: import("openclaw/plugin-sdk").OpenClawConfig;
+  channelRuntime: PluginRuntime["channel"];
+  apiOpts: WorkChatApiOptions;
+  log: (msg: string) => void;
+  errLog: (m: string) => void;
+};
+
+/** Persist agent/user ids discovered from AGENT_CREATED / INIT_AGENT events. */
+async function handleAgentLifecycleEvent(
+  frameType: "agent_created" | "init_agent",
+  result: ParseWorkChatFrameResult,
+  deps: ProcessFrameDeps,
+): Promise<void> {
+  const eventData = result.eventData;
+  if (!eventData) return;
+
+  const agentId = String(eventData.id ?? eventData.agentId ?? "");
+  if (!agentId) {
+    logger.warn(`${frameType}: missing agent id, ignoring`);
+    return;
+  }
+  const userId = String(eventData.futureId ?? eventData.userId ?? "");
+
+  logger.info(`${frameType}: agentId=${agentId} userId=${userId ? "present" : "missing"}`);
+  deps.log(`${frameType}: agentId=${agentId}`);
+
+  // Rebind detection must happen BEFORE pruning empties the index (see the
+  // matching note in the binding listener): a rebind always registers under a
+  // FRESH agent-scoped key so the gateway restarts it — the QR login flow
+  // force-stops the channel with a manual-stop mark, and a reused account id
+  // would stay stopped after the config reload.
+  const isRebind = listWorkChatAccountIdsCount() > 0;
+
+  // Rebind semantics: one active agent per host. Before persisting the new
+  // binding, remove every registered account bound to a different agent
+  // (a re-scan creates a new platform agent; the old one is deleted there).
+  try {
+    const removed = await pruneStaleWorkChatAccounts(agentId);
+    if (removed.length > 0) {
+      deps.log(`rebind: removed stale account(s): ${removed.join(", ")}`);
+    }
+  } catch (err) {
+    logger.error(`rebind cleanup failed: ${String(err)}`);
+  }
+
+  // The bound agent becomes the account: `default` for the primary install,
+  // or a fresh agent-scoped key on rebind.
+  const { completeWorkChatBinding } = await import("../auth/login-qr.js");
+  const accountId = frameType === "init_agent"
+    ? (isRebind ? `agent-${agentId}` : "default")
+    : deps.accountId;
+
+  try {
+    saveWorkChatAccount(accountId, {
+      agentId,
+      ...(userId ? { userId } : {}),
+    });
+    registerWorkChatAccountId(accountId);
+    // Bind the account to the incoming agent for message routing. agentId
+    // comes from the event; userId (futureId) is the WorkChat user.
+    const { bindAgentToAccount } = await import("../auth/bind-agent.js");
+    await bindAgentToAccount(accountId, agentId, userId);
+    logger.info(`${frameType}: bound agent to account accountId=${accountId}`);
+    await triggerWorkChatChannelReload();
+  } catch (err) {
+    logger.error(`${frameType}: failed to save account data err=${String(err)}`);
+  }
+
+  // INIT_AGENT closes the pending QR binding session (if any).
+  if (frameType === "init_agent") {
+    const resolved = completeWorkChatBinding({
+      accountId,
+      agentId,
+      ...(userId ? { userId } : {}),
+    });
+    if (resolved) {
+      deps.log(`绑定完成: agentId=${agentId}`);
+    }
+  }
+
+  if (frameType === "agent_created") {
+    // Ack the platform that the local side is ready (best-effort, non-fatal).
+    void notifyAgentCreatedStatus(deps.apiOpts, agentId);
+  }
+}
+
+function listWorkChatAccountIdsCount(): number {
+  return listIndexedWorkChatAccountIds().length;
+}
+
+// Typing-indicator helper versions: the host renamed the subpath between
+// releases (2026.3.x exports openclaw/plugin-sdk/channel-runtime, 2026.8.x
+// exports openclaw/plugin-sdk/channel-message). Load whichever resolves —
+// both export createTypingCallbacks. WorkChat has no typing API, so the
+// callbacks are no-op; only the dispatcher lifecycle shape matters.
+let createTypingCallbacksPromise: Promise<((opts: unknown) => unknown) | null> | undefined;
+function loadCreateTypingCallbacks(): Promise<((opts: unknown) => unknown) | null> {
+  createTypingCallbacksPromise ??= (async () => {
+    for (const specifier of ["openclaw/plugin-sdk/channel-runtime", "openclaw/plugin-sdk/channel-message"]) {
+      try {
+        // Variable specifier keeps the import dynamic so both host versions
+        // resolve at runtime instead of one failing at bundle time.
+        const mod = (await import(specifier)) as { createTypingCallbacks?: (opts: unknown) => unknown };
+        if (typeof mod?.createTypingCallbacks === "function") return mod.createTypingCallbacks;
+      } catch {
+        // subpath not present on this host — try the next
+      }
+    }
+    return null;
+  })();
+  return createTypingCallbacksPromise;
+}
+
+async function createNoopTypingCallbacks(): Promise<unknown> {
+  const createTypingCallbacks = await loadCreateTypingCallbacks();
+  if (!createTypingCallbacks) {
+    // Host exposes neither subpath: minimal lifecycle stub.
+    return { start: () => {}, stop: () => {} };
+  }
+  return createTypingCallbacks({
+    start: async () => {},
+    stop: async () => {},
+    onStartError: () => {},
+    onStopError: () => {},
+    keepaliveIntervalMs: 5000,
+  });
+}
+
+
+
+/**
+ * Process a single parsed inbound frame: lifecycle events are persisted,
+ * AGENT_MESSAGE frames are authorized, routed, and dispatched into the core
+ * reply pipeline.
+ */
+export async function processOneFrame(
+  result: ParseWorkChatFrameResult,
+  rawFrame: string,
+  deps: ProcessFrameDeps,
+): Promise<void> {
+  if (!deps?.channelRuntime) {
+    logger.error(`processOneFrame: channelRuntime is undefined, skipping type=${result.type}`);
+    return;
+  }
+
+  switch (result.type) {
+    case "agent_created":
+    case "init_agent":
+      await handleAgentLifecycleEvent(result.type, result, deps);
+      return;
+    case "agent_updated":
+      logger.info(`${result.type}: no local action`);
+      return;
+    case "agent_deleted": {
+      // The platform deleted this agent (e.g. a re-scan replaced it): tear
+      // down the local account binding so no dead monitor keeps running.
+      const eventData = result.eventData;
+      const deletedAgentId = String(eventData?.id ?? eventData?.agentId ?? "").trim();
+      if (!deletedAgentId) {
+        logger.warn("agent_deleted: missing agent id, ignoring");
+        return;
+      }
+      const victim = listIndexedWorkChatAccountIds()
+        .find(id => loadWorkChatAccount(id)?.agentId?.trim() === deletedAgentId);
+      if (victim) {
+        try {
+          await removeWorkChatAccountBinding(victim);
+          await triggerWorkChatChannelReload();
+          deps.log(`agent_deleted: removed account=${victim} agent=${deletedAgentId}`);
+        } catch (err) {
+          logger.error(`agent_deleted: failed to remove account=${victim}: ${String(err)}`);
+        }
+      } else {
+        logger.info(`agent_deleted: agent=${deletedAgentId} not bound locally, ignoring`);
+      }
+      return;
+    }
+    case "ignored":
+      // Unhandled-but-recognized frames (TOOLS_LIST/SKILLS_LIST/SKILL_DO_REMIND/
+      // CRON_REMIND...): log the raw kind so platform pushes are observable.
+      logger.debug(`ignored frame kind=${result.ignoredKind ?? "(unknown)"}`);
+      return;
+    case "ping":
+    case "disconnect":
+      return;
+    case "agent_message":
+      break;
+    default:
+      return;
+  }
+
+  const message = result.message;
+  if (!message) return;
+  if (!message.text?.trim()) {
+    logger.debug("inbound: empty body, ignoring");
+    return;
+  }
+
+  const receivedAt = Date.now();
+  const debug = isDebugMode(deps.accountId);
+  const debugTrace: string[] = [];
+  const debugTs: Record<string, number> = { received: receivedAt };
+
+  const ctx = workChatMessageToMsgContext(message, deps.accountId);
+  logger.info(
+    `inbound: from=${ctx.From} to=${ctx.To} bodyLen=${ctx.Body.length} conversationId=${ctx.ConversationId ?? "(none)"}`,
+  );
+  logger.debug(`inbound raw frame: ${rawFrame.slice(0, 200)}`);
+
+  // --- Slash commands (handled locally, never dispatched to AI) ---
+  if (ctx.Body.trim().startsWith("/")) {
+    const slashResult = await handleSlashCommand(ctx.Body, {
+      account: deps.account,
+      to: ctx.To,
+      agentId: ctx.AgentId,
+      log: deps.log,
+      errLog: deps.errLog,
+    }, receivedAt);
+    if (slashResult.handled) {
+      return;
+    }
+  }
+
+  // --- Framework command authorization ---
+  const rawBody = ctx.Body?.trim() ?? "";
+  ctx.CommandBody = rawBody;
+  const senderId = ctx.From;
+
+  const { senderAllowedForCommands, commandAuthorized } =
+    await resolveSenderCommandAuthorizationWithRuntime({
+      cfg: deps.config,
+      rawBody,
+      isGroup: false,
+      dmPolicy: "pairing",
+      configuredAllowFrom: [],
+      configuredGroupAllowFrom: [],
+      senderId,
+      isSenderAllowed: (id: string, list: string[]) => list.length === 0 || list.includes(id),
+      /** Pairing: framework credentials `*-allowFrom.json`, with account `userId` fallback for legacy installs. */
+      readAllowFromStore: async () => {
+        const fromStore = readFrameworkAllowFromList(deps.accountId);
+        if (fromStore.length > 0) return fromStore;
+        const uid = loadWorkChatAccount(deps.accountId)?.userId?.trim();
+        return uid ? [uid] : [];
+      },
+      runtime: deps.channelRuntime.commands,
+    });
+
+  const directDmOutcome = resolveDirectDmAuthorizationOutcome({
+    isGroup: false,
+    dmPolicy: "pairing",
+    senderAllowedForCommands,
+  });
+
+  if (directDmOutcome === "disabled" || directDmOutcome === "unauthorized") {
+    logger.info(
+      `authorization: dropping message from=${senderId} outcome=${directDmOutcome}`,
+    );
+    return;
+  }
+
+  ctx.CommandAuthorized = commandAuthorized;
+  logger.debug(
+    `authorization: senderId=${senderId} commandAuthorized=${String(commandAuthorized)} senderAllowed=${String(senderAllowedForCommands)}`,
+  );
+
+  if (debug) {
+    debugTrace.push(
+      "── 鉴权 & 路由 ──",
+      `│ auth: cmdAuthorized=${String(commandAuthorized)} senderAllowed=${String(senderAllowedForCommands)}`,
+    );
+  }
+
+  const route = deps.channelRuntime.routing.resolveAgentRoute({
+    cfg: deps.config,
+    channel: "openclaw-workchat",
+    accountId: deps.accountId,
+    peer: { kind: "direct", id: ctx.To },
+  });
+  logger.debug(
+    `resolveAgentRoute: agentId=${route.agentId ?? "(none)"} sessionKey=${route.sessionKey ?? "(none)"} mainSessionKey=${route.mainSessionKey ?? "(none)"}`,
+  );
+  if (!route.agentId) {
+    logger.error(
+      `resolveAgentRoute: no agentId resolved for peer=${ctx.To} accountId=${deps.accountId} — message will not be dispatched`,
+    );
+  }
+
+  if (debug) {
+    debugTrace.push(`│ route: agent=${route.agentId ?? "none"} session=${route.sessionKey ?? "none"}`);
+    debugTs.preDispatch = Date.now();
+  }
+  // Propagate the resolved session key into ctx so dispatchReplyFromConfig uses
+  // the correct session (matching the dmScope from config) instead of falling back.
+  ctx.SessionKey = route.sessionKey;
+  const storePath = deps.channelRuntime.session.resolveStorePath(deps.config.session?.store, {
+    agentId: route.agentId,
+  });
+  const finalized = deps.channelRuntime.reply.finalizeInboundContext(
+    ctx as Parameters<typeof deps.channelRuntime.reply.finalizeInboundContext>[0],
+  );
+
+  logger.info(
+    `inbound: from=${finalized.From} to=${finalized.To} bodyLen=${(finalized.Body ?? "").length}`,
+  );
+  logger.debug(`inbound context: ${redactBody(JSON.stringify(finalized))}`);
+
+  await deps.channelRuntime.session.recordInboundSession({
+    storePath,
+    sessionKey: route.sessionKey,
+    ctx: finalized as Parameters<typeof deps.channelRuntime.session.recordInboundSession>[0]["ctx"],
+    updateLastRoute: {
+      sessionKey: route.mainSessionKey,
+      channel: "openclaw-workchat",
+      to: ctx.To,
+      accountId: deps.accountId,
+    },
+    onRecordError: (err) => deps.errLog(`recordInboundSession: ${String(err)}`),
+  });
+  logger.debug(`recordInboundSession: done storePath=${storePath} sessionKey=${route.sessionKey ?? "(none)"}`);
+
+  const humanDelay = deps.channelRuntime.reply.resolveHumanDelayConfig(deps.config, route.agentId);
+
+  const typingCallbacks = await createNoopTypingCallbacks();
+
+  /** Delivery records populated synchronously at deliver() entry, safe to read in finally. */
+  const debugDeliveries: Array<{ textLen: number; preview: string; ts: number }> = [];
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    deps.channelRuntime.reply.createReplyDispatcherWithTyping({
+      humanDelay,
+      // Shape comes from a host-version-dependent loader; the local SDK's
+      // TypingCallbacks type does not apply cleanly across versions.
+      typingCallbacks: typingCallbacks as any,
+      deliver: async (payload) => {
+        // Lazy-load send + markdown filter to keep registration / QR binding import-light.
+        const [{ replyWorkChatMessage }, { StreamingMarkdownFilter }] = await Promise.all([
+          import("./send.js"),
+          import("./markdown-filter.js"),
+        ]);
+        const rawText = String(payload.text ?? "");
+        const f = new StreamingMarkdownFilter();
+        let text = f.feed(rawText) + f.flush();
+
+        logger.info(`outbound: to=${ctx.To} textLen=${text.length}`);
+
+        if (debug) {
+          debugDeliveries.push({
+            textLen: text.length,
+            preview: `${text.slice(0, 60)}${text.length > 60 ? "…" : ""}`,
+            ts: Date.now(),
+          });
+        }
+
+        const sendingResult = await applyWorkChatMessageSendingHook({
+          to: ctx.To,
+          text,
+          accountId: deps.accountId,
+        });
+        if (sendingResult.cancelled) {
+          logger.info(`outbound: cancelled by message_sending hook to=${ctx.To}`);
+          return;
+        }
+        text = sendingResult.text;
+
+        try {
+          const result = await replyWorkChatMessage({
+            account: {
+              ...deps.account,
+              agentId: ctx.AgentId ?? deps.account.agentId,
+              userId: ctx.From || deps.account.userId,
+            },
+            to: ctx.To,
+            text,
+            replyToMessageId: ctx.MessageSid,
+            conversationId: ctx.ConversationId,
+            agentId: ctx.AgentId,
+            last: true,
+          });
+          emitWorkChatMessageSent({ to: ctx.To, content: text, success: true, accountId: deps.accountId });
+          logger.info(`outbound: reply sent OK to=${ctx.To} messageId=${result.messageId}`);
+        } catch (err) {
+          emitWorkChatMessageSent({ to: ctx.To, content: text, success: false, error: String(err), accountId: deps.accountId });
+          logger.error(`outbound: FAILED to=${ctx.To} err=${String(err)}`);
+          throw err;
+        }
+      },
+      onError: (err, info) => {
+        deps.errLog(`workchat reply ${info.kind}: ${String(err)}`);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const notice = `⚠️ 消息发送失败：${errMsg}`;
+        void sendWorkChatErrorNotice({
+          account: deps.account,
+          to: ctx.To,
+          message: notice,
+          agentId: ctx.AgentId,
+          errLog: deps.errLog,
+        });
+      },
+    });
+
+  logger.debug(`dispatchReplyFromConfig: starting agentId=${route.agentId ?? "(none)"}`);
+  try {
+    await deps.channelRuntime.reply.withReplyDispatcher({
+      dispatcher,
+      run: () =>
+        deps.channelRuntime.reply.dispatchReplyFromConfig({
+          ctx: finalized,
+          cfg: deps.config,
+          dispatcher,
+          replyOptions: { ...replyOptions, disableBlockStreaming: true },
+        }),
+    });
+    logger.debug(`dispatchReplyFromConfig: done agentId=${route.agentId ?? "(none)"}`);
+  } catch (err) {
+    logger.error(
+      `dispatchReplyFromConfig: error agentId=${route.agentId ?? "(none)"} err=${String(err)}`,
+    );
+    throw err;
+  } finally {
+    markDispatchIdle();
+
+    if (debug) {
+      const dispatchDoneAt = Date.now();
+      const inboundProcessMs = (debugTs.preDispatch ?? receivedAt) - receivedAt;
+      const aiMs = dispatchDoneAt - (debugTs.preDispatch ?? receivedAt);
+      const totalTime = dispatchDoneAt - receivedAt;
+
+      if (debugDeliveries.length > 0) {
+        debugTrace.push("── 回复 ──");
+        for (const d of debugDeliveries) {
+          debugTrace.push(`│ textLen=${d.textLen}`, `│ text="${d.preview}"`);
+        }
+        const firstTs = debugDeliveries[0].ts;
+        debugTrace.push(`│ deliver耗时: ${dispatchDoneAt - firstTs}ms`);
+      } else {
+        debugTrace.push("── 回复 ──", "│ (deliver未捕获)");
+      }
+
+      debugTrace.push(
+        "── 耗时 ──",
+        `├ 入站处理(auth+route): ${inboundProcessMs}ms`,
+        `├ AI生成+回复: ${aiMs}ms`,
+        `├ 总耗时: ${totalTime}ms`,
+      );
+
+      const timingText = `⏱ Debug 全链路\n${debugTrace.join("\n")}`;
+      logger.info(`debug-timing: sending to=${ctx.To}`);
+      void import("./send.js").then(({ pushWorkChatMessage }) =>
+        pushWorkChatMessage({
+          account: {
+            ...deps.account,
+            agentId: ctx.AgentId ?? deps.account.agentId,
+            userId: ctx.From || deps.account.userId,
+          },
+          to: ctx.To,
+          text: timingText,
+          agentId: ctx.AgentId,
+        }),
+      ).catch((debugErr) => {
+        logger.error(`debug-timing: send FAILED err=${String(debugErr)}`);
+      });
+    }
+  }
+}