@workclaw/openclaw-workclaw 1.0.1 → 1.0.12

package/src/gateway/message-context.ts

@@ -1,422 +1,422 @@
-import type { PluginRuntime } from 'openclaw/plugin-sdk'
-
-/** Channel/plugin name constant */
-export const OPENCLAW_WORKCLAW_CHANNEL = 'openclaw-workclaw'
-
-export interface InboundMessage {
-  text: string
-  to: string
-  from: string
-  chatType: 'dm' | 'group'
-  messageId: string
-  rawPayload: string
-  timestamp: number
-}
-
-export interface InboundContextPayload {
-  [key: string]: unknown
-  Body: string
-  BodyForAgent: string
-  RawBody: string
-  From: string
-  To: string
-  ChatType: 'dm' | 'group'
-  Provider: string
-  Surface: string
-  Timestamp: number
-  AccountId: string
-  AgentId?: string
-  MessageSid?: string
-  OriginatingChannel: string
-  OriginatingTo: string
-}
-
-export type WorkClawMessageType
-  = | 'agent_message' // 正常的业务消息
-    | 'ping' // 需要回复 pong 的消息
-    | 'disconnect' // 断开连接的消息
-    | 'agent_created' // 创建账户事件
-    | 'agent_updated' // 更新账户事件
-    | 'agent_deleted' // 删除账户事件
-    | 'tools_list' // 获取工具列表事件
-    | 'skills_list' // 获取 skills 列表事件
-    | 'skills_event' // skills 相关事件（create/update/delete/list/get/invoke）
-    | 'init_agent' // 初始化智能体事件
-    | 'ignored' // 忽略的消息（未知类型）
-
-export interface ParseWorkClawResult {
-  type: WorkClawMessageType
-  message?: {
-    text: string
-    userId: string
-    openConversationId: string
-    messageId: string
-    agentId?: string | number
-  }
-  pongData?: any // 用于回复 pong 的数据
-  eventData?: any // 事件数据（用于 AGENT_CREATED/UPDATED/DELETED）
-  skillsEvent?: {
-    // skills 事件数据
-    topic: string // skills/create, skills/update, skills/delete, skills/list, skills/get, skills/invoke
-    requestId: string
-    callbackUrl: string
-    authToken?: string
-    data: any
-  }
-}
-
-export function parseInboundMessage(data: string, allowRawJsonPayload?: boolean): Partial<InboundMessage> {
-  let input: any = {}
-  try {
-    input = data ? JSON.parse(data) : {}
-  }
-  catch {
-    // Not JSON, treat as plain text
-  }
-
-  const text
-    = typeof input.text === 'string'
-      ? input.text
-      : typeof input.message === 'string'
-        ? input.message
-        : typeof input.body === 'string'
-          ? input.body
-          : data
-
-  const to = String(input.to ?? input.chatId ?? input.target ?? '')
-  const from = String(input.from ?? input.senderId ?? input.userId ?? '')
-  const chatType = String(input.chatType || '').toLowerCase() === 'group' ? 'group' : 'dm'
-  const messageId = String(input.messageId ?? input.id ?? '')
-  const rawPayload = allowRawJsonPayload ? JSON.stringify(input ?? {}) : data
-
-  return {
-    text,
-    to,
-    from,
-    chatType,
-    messageId,
-    rawPayload,
-  }
-}
-
-export function parseWorkClawMessage(data: string, log?: {
-  info?: (msg: string) => void
-  warn?: (msg: string) => void
-  error?: (msg: string) => void
-}): ParseWorkClawResult | null {
-  // {"specVersion":"1.0","type":"EVENT","metadata":{"time":"1773749163831","event":"INIT_AGENT","contentType":"application/json"},"data":"\"12557533957824965\""}
-  let input: any = {}
-  try {
-    input = data ? JSON.parse(data) : {}
-  }
-  catch {
-    log?.info?.(`Failed to parse message data=${data}`)
-    return null
-  }
-
-  // Handle plain text ping
-  if (typeof input === 'string' && input.toLowerCase() === 'ping') {
-    return {
-      type: 'ping',
-      pongData: input,
-    }
-  }
-
-  const envelope = input && typeof input === 'object' ? input : { data: input }
-  const topic = envelope?.metadata?.topic
-  const type = String(envelope?.type || '').trim().toUpperCase()
-  const topicLower = String(topic || '').trim().toLowerCase()
-
-  if (type === 'INIT_AGENT') {
-    let parsedData = envelope?.data
-    if (typeof parsedData === 'string') {
-      try {
-        parsedData = JSON.parse(parsedData)
-      }
-      catch {
-        // 解析失败，保持原样
-      }
-    }
-
-    return {
-      type: 'init_agent',
-      eventData: parsedData,
-    }
-  }
-
-  // Handle SYSTEM messages
-  if (type === 'SYSTEM') {
-    if (topicLower === 'ping') {
-      return {
-        type: 'ping',
-        pongData: envelope?.data,
-      }
-    }
-    if (topicLower === 'disconnect') {
-      return {
-        type: 'disconnect',
-      }
-    }
-    // Unknown system message type, ignore
-    return {
-      type: 'ignored',
-    }
-  }
-
-  // Handle EVENT messages (AGENT_CREATED, AGENT_UPDATED, AGENT_DELETED, TOOLS_LIST, SKILLS_LIST, INIT_AGENT)
-  if (type === 'EVENT') {
-    const eventType = String(envelope?.metadata?.event || '').trim().toUpperCase()
-
-    // 解析 data 字段（可能是 JSON 字符串）
-    let parsedData = envelope?.data
-    if (typeof parsedData === 'string') {
-      try {
-        parsedData = JSON.parse(parsedData)
-      }
-      catch {
-        // 解析失败，保持原样
-      }
-    }
-
-    if (eventType === 'AGENT_CREATED') {
-      return {
-        type: 'agent_created',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'AGENT_UPDATED') {
-      return {
-        type: 'agent_updated',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'AGENT_DELETED') {
-      return {
-        type: 'agent_deleted',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'TOOLS_LIST') {
-      return {
-        type: 'tools_list',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'SKILLS_LIST') {
-      return {
-        type: 'skills_list',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'INIT_AGENT') {
-      return {
-        type: 'init_agent',
-        eventData: parsedData,
-      }
-    }
-
-    if (eventType === 'SKILL_DO_REMIND') {
-      const eventTopic = String(parsedData?.dotype || '').toLowerCase()
-      return {
-        type: 'skills_event',
-        skillsEvent: {
-          topic: `skills/${eventTopic}`,
-          requestId: '',
-          callbackUrl: '',
-          authToken: '',
-          data: parsedData,
-        },
-      }
-    }
-
-    // Unknown event type, ignore
-    return {
-      type: 'ignored',
-    }
-  }
-
-  // Only process CALLBACK type with AGENT_MESSAGE topic
-  if (type !== 'CALLBACK' || String(topic || '').trim().toUpperCase() !== 'AGENT_MESSAGE') {
-    return {
-      type: 'ignored',
-    }
-  }
-
-  // 解析 data 字段（可能是 JSON 字符串）
-  let payload = envelope?.data || {}
-  if (typeof payload === 'string') {
-    try {
-      payload = JSON.parse(payload)
-    }
-    catch {
-      // 解析失败，保持原样
-    }
-  }
-
-  const text
-    = typeof payload?.message?.content === 'string'
-      ? payload.message.content
-      : typeof payload?.message === 'string'
-        ? payload.message
-        : ''
-
-  return {
-    type: 'agent_message',
-    message: {
-      text,
-      userId: String(payload?.userId ?? ''),
-      openConversationId: String(payload?.conversationId ?? ''),
-      messageId: String(payload?.msgId ?? ''),
-      agentId: payload?.agentId,
-    },
-  }
-}
-
-/**
- * Build inbound context for WorkClaw channel.
- *
- * When pluginRuntime is provided, performs full session handling:
- * - resolveStorePath, readSessionUpdatedAt, formatInboundEnvelope
- * - finalizeInboundContext, recordInboundSession
- *
- * @param message - The inbound message
- * @param accountId - Account ID
- * @param config - Account config (OpenclawWorkclawConfig)
- * @param agentId - Target agent ID (optional)
- * @param pluginRuntime - OpenClaw plugin runtime (optional, enables full session handling)
- * @param recordSession - Whether to record session (default true)
- * @param log 日志对象（可选）
- * @param {Function} [log.info] - 信息日志函数
- * @param {Function} [log.error] - 错误日志函数
- * @param {Function} [log.warn] - 警告日志函数
- */
-export async function buildInboundContext(
-  message: InboundMessage,
-  accountId: string,
-  config: any,
-  agentId?: string,
-  pluginRuntime?: PluginRuntime,
-  recordSession: boolean = true,
-  log?: { info?: (msg: string) => void, warn?: (msg: string) => void, error?: (msg: string) => void },
-): Promise<InboundContextPayload> {
-  // 尝试从 rawPayload 中提取已有的 sessionKey（新建话题时 openclaw 会生成新的 session）
-  let existingSessionKey: string | undefined
-  try {
-    const rawPayload = JSON.parse(message.rawPayload)
-    existingSessionKey = rawPayload.sessionKey
-  }
-  catch {
-    // ignore
-  }
-
-  const peerId = message.from
-  const computedSessionKey = existingSessionKey
-    || (agentId && agentId !== 'main'
-      ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
-      : undefined)
-
-  const sessionKey = computedSessionKey || (agentId && agentId !== 'main'
-    ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
-    : undefined)
-
-  // Basic context (used as base for both paths)
-  const result: InboundContextPayload = {
-    Body: message.text,
-    BodyForAgent: message.rawPayload || message.text,
-    RawBody: JSON.stringify(message),
-    From: message.from,
-    To: message.to,
-    ChatType: message.chatType,
-    Provider: OPENCLAW_WORKCLAW_CHANNEL,
-    Surface: OPENCLAW_WORKCLAW_CHANNEL,
-    Timestamp: message.timestamp,
-    AccountId: accountId,
-    AgentId: agentId,
-    MessageSid: message.messageId,
-    OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
-    OriginatingTo: message.to,
-  }
-
-  if (sessionKey) {
-    result.SessionKey = sessionKey
-  }
-
-  // If no pluginRuntime provided, return basic context without session recording
-  if (!pluginRuntime) {
-    return result
-  }
-
-  // Full session handling path
-  const storePath = pluginRuntime.channel.session.resolveStorePath(config.session?.store, { agentId })
-  log?.info?.(`[Session] storePath=${storePath}, agentId=${agentId}, sessionKey=${sessionKey}`)
-
-  // 获取 envelope 格式选项
-  const envelopeOptions = pluginRuntime.channel.reply.resolveEnvelopeFormatOptions(config)
-
-  // 获取上次的 session 更新时间
-  const previousTimestamp = pluginRuntime.channel.session.readSessionUpdatedAt({
-    storePath,
-    sessionKey: sessionKey!,
-  })
-  log?.info?.(`[Session] previousTimestamp=${previousTimestamp}`)
-
-  // 格式化 envelope（Body 用于日志/历史，BodyForAgent 用于 AI）
-  const fromLabel = message.to
-  const body = pluginRuntime.channel.reply.formatInboundEnvelope({
-    channel: OPENCLAW_WORKCLAW_CHANNEL,
-    from: fromLabel,
-    timestamp: message.timestamp,
-    body: message.text,
-    chatType: message.chatType,
-    sender: { name: message.to, id: message.to },
-    previousTimestamp,
-    envelope: envelopeOptions,
-  })
-
-  // 构建完整的 ctx
-  const finalized = pluginRuntime.channel.reply.finalizeInboundContext({
-    Body: body,
-    BodyForAgent: message.text,
-    RawBody: JSON.stringify(message),
-    CommandBody: message.text,
-    From: message.from,
-    To: message.to,
-    SessionKey: sessionKey,
-    AccountId: accountId,
-    ChatType: message.chatType,
-    ConversationLabel: fromLabel,
-    Provider: OPENCLAW_WORKCLAW_CHANNEL,
-    Surface: 'openclaw-workclaw_dm',
-    MessageSid: message.messageId,
-    Timestamp: message.timestamp,
-    OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
-    OriginatingTo: message.to,
-  })
-
-  // 记录 session（需要在 dispatchReplyWithBufferedBlockDispatcher 之前调用）
-  // 这样 OpenClaw 才能在工具执行时正确关联 session
-  if (sessionKey && recordSession) {
-    try {
-      await pluginRuntime.channel.session.recordInboundSession({
-        storePath,
-        sessionKey: finalized.SessionKey || sessionKey,
-        ctx: finalized,
-        updateLastRoute: {
-          sessionKey,
-          channel: OPENCLAW_WORKCLAW_CHANNEL,
-          to: message.to,
-          accountId,
-        },
-        onRecordError: (err: unknown) => {
-          log?.error?.(`[Session] recordInboundSession failed: ${String(err)}`)
-        },
-      })
-      log?.info?.(`[Session] Recorded session for key=${sessionKey}`)
-    }
-    catch (err) {
-      log?.warn?.(`[Session] recordInboundSession error: ${String(err)}`)
-    }
-  }
-
-  return finalized
-}
+import type { PluginRuntime } from 'openclaw/plugin-sdk'
+
+/** Channel/plugin name constant */
+export const OPENCLAW_WORKCLAW_CHANNEL = 'openclaw-workclaw'
+
+export interface InboundMessage {
+  text: string
+  to: string
+  from: string
+  chatType: 'dm' | 'group'
+  messageId: string
+  rawPayload: string
+  timestamp: number
+}
+
+export interface InboundContextPayload {
+  [key: string]: unknown
+  Body: string
+  BodyForAgent: string
+  RawBody: string
+  From: string
+  To: string
+  ChatType: 'dm' | 'group'
+  Provider: string
+  Surface: string
+  Timestamp: number
+  AccountId: string
+  AgentId?: string
+  MessageSid?: string
+  OriginatingChannel: string
+  OriginatingTo: string
+}
+
+export type WorkClawMessageType
+  = | 'agent_message' // 正常的业务消息
+    | 'ping' // 需要回复 pong 的消息
+    | 'disconnect' // 断开连接的消息
+    | 'agent_created' // 创建账户事件
+    | 'agent_updated' // 更新账户事件
+    | 'agent_deleted' // 删除账户事件
+    | 'tools_list' // 获取工具列表事件
+    | 'skills_list' // 获取 skills 列表事件
+    | 'skills_event' // skills 相关事件（create/update/delete/list/get/invoke）
+    | 'init_agent' // 初始化智能体事件
+    | 'ignored' // 忽略的消息（未知类型）
+
+export interface ParseWorkClawResult {
+  type: WorkClawMessageType
+  message?: {
+    text: string
+    userId: string
+    openConversationId: string
+    messageId: string
+    agentId?: string | number
+  }
+  pongData?: any // 用于回复 pong 的数据
+  eventData?: any // 事件数据（用于 AGENT_CREATED/UPDATED/DELETED）
+  skillsEvent?: {
+    // skills 事件数据
+    topic: string // skills/create, skills/update, skills/delete, skills/list, skills/get, skills/invoke
+    requestId: string
+    callbackUrl: string
+    authToken?: string
+    data: any
+  }
+}
+
+export function parseInboundMessage(data: string, allowRawJsonPayload?: boolean): Partial<InboundMessage> {
+  let input: any = {}
+  try {
+    input = data ? JSON.parse(data) : {}
+  }
+  catch {
+    // Not JSON, treat as plain text
+  }
+
+  const text
+    = typeof input.text === 'string'
+      ? input.text
+      : typeof input.message === 'string'
+        ? input.message
+        : typeof input.body === 'string'
+          ? input.body
+          : data
+
+  const to = String(input.to ?? input.chatId ?? input.target ?? '')
+  const from = String(input.from ?? input.senderId ?? input.userId ?? '')
+  const chatType = String(input.chatType || '').toLowerCase() === 'group' ? 'group' : 'dm'
+  const messageId = String(input.messageId ?? input.id ?? '')
+  const rawPayload = allowRawJsonPayload ? JSON.stringify(input ?? {}) : data
+
+  return {
+    text,
+    to,
+    from,
+    chatType,
+    messageId,
+    rawPayload,
+  }
+}
+
+export function parseWorkClawMessage(data: string, log?: {
+  info?: (msg: string) => void
+  warn?: (msg: string) => void
+  error?: (msg: string) => void
+}): ParseWorkClawResult | null {
+  // {"specVersion":"1.0","type":"EVENT","metadata":{"time":"1773749163831","event":"INIT_AGENT","contentType":"application/json"},"data":"\"12557533957824965\""}
+  let input: any = {}
+  try {
+    input = data ? JSON.parse(data) : {}
+  }
+  catch {
+    log?.info?.(`Failed to parse message data=${data}`)
+    return null
+  }
+
+  // Handle plain text ping
+  if (typeof input === 'string' && input.toLowerCase() === 'ping') {
+    return {
+      type: 'ping',
+      pongData: input,
+    }
+  }
+
+  const envelope = input && typeof input === 'object' ? input : { data: input }
+  const topic = envelope?.metadata?.topic
+  const type = String(envelope?.type || '').trim().toUpperCase()
+  const topicLower = String(topic || '').trim().toLowerCase()
+
+  if (type === 'INIT_AGENT') {
+    let parsedData = envelope?.data
+    if (typeof parsedData === 'string') {
+      try {
+        parsedData = JSON.parse(parsedData)
+      }
+      catch {
+        // 解析失败，保持原样
+      }
+    }
+
+    return {
+      type: 'init_agent',
+      eventData: parsedData,
+    }
+  }
+
+  // Handle SYSTEM messages
+  if (type === 'SYSTEM') {
+    if (topicLower === 'ping') {
+      return {
+        type: 'ping',
+        pongData: envelope?.data,
+      }
+    }
+    if (topicLower === 'disconnect') {
+      return {
+        type: 'disconnect',
+      }
+    }
+    // Unknown system message type, ignore
+    return {
+      type: 'ignored',
+    }
+  }
+
+  // Handle EVENT messages (AGENT_CREATED, AGENT_UPDATED, AGENT_DELETED, TOOLS_LIST, SKILLS_LIST, INIT_AGENT)
+  if (type === 'EVENT') {
+    const eventType = String(envelope?.metadata?.event || '').trim().toUpperCase()
+
+    // 解析 data 字段（可能是 JSON 字符串）
+    let parsedData = envelope?.data
+    if (typeof parsedData === 'string') {
+      try {
+        parsedData = JSON.parse(parsedData)
+      }
+      catch {
+        // 解析失败，保持原样
+      }
+    }
+
+    if (eventType === 'AGENT_CREATED') {
+      return {
+        type: 'agent_created',
+        eventData: parsedData,
+      }
+    }
+    if (eventType === 'AGENT_UPDATED') {
+      return {
+        type: 'agent_updated',
+        eventData: parsedData,
+      }
+    }
+    if (eventType === 'AGENT_DELETED') {
+      return {
+        type: 'agent_deleted',
+        eventData: parsedData,
+      }
+    }
+    if (eventType === 'TOOLS_LIST') {
+      return {
+        type: 'tools_list',
+        eventData: parsedData,
+      }
+    }
+    if (eventType === 'SKILLS_LIST') {
+      return {
+        type: 'skills_list',
+        eventData: parsedData,
+      }
+    }
+    if (eventType === 'INIT_AGENT') {
+      return {
+        type: 'init_agent',
+        eventData: parsedData,
+      }
+    }
+
+    if (eventType === 'SKILL_DO_REMIND') {
+      const eventTopic = String(parsedData?.dotype || '').toLowerCase()
+      return {
+        type: 'skills_event',
+        skillsEvent: {
+          topic: `skills/${eventTopic}`,
+          requestId: '',
+          callbackUrl: '',
+          authToken: '',
+          data: parsedData,
+        },
+      }
+    }
+
+    // Unknown event type, ignore
+    return {
+      type: 'ignored',
+    }
+  }
+
+  // Only process CALLBACK type with AGENT_MESSAGE topic
+  if (type !== 'CALLBACK' || String(topic || '').trim().toUpperCase() !== 'AGENT_MESSAGE') {
+    return {
+      type: 'ignored',
+    }
+  }
+
+  // 解析 data 字段（可能是 JSON 字符串）
+  let payload = envelope?.data || {}
+  if (typeof payload === 'string') {
+    try {
+      payload = JSON.parse(payload)
+    }
+    catch {
+      // 解析失败，保持原样
+    }
+  }
+
+  const text
+    = typeof payload?.message?.content === 'string'
+      ? payload.message.content
+      : typeof payload?.message === 'string'
+        ? payload.message
+        : ''
+
+  return {
+    type: 'agent_message',
+    message: {
+      text,
+      userId: String(payload?.userId ?? ''),
+      openConversationId: String(payload?.conversationId ?? ''),
+      messageId: String(payload?.msgId ?? ''),
+      agentId: payload?.agentId,
+    },
+  }
+}
+
+/**
+ * Build inbound context for WorkClaw channel.
+ *
+ * When pluginRuntime is provided, performs full session handling:
+ * - resolveStorePath, readSessionUpdatedAt, formatInboundEnvelope
+ * - finalizeInboundContext, recordInboundSession
+ *
+ * @param message - The inbound message
+ * @param accountId - Account ID
+ * @param config - Account config (OpenclawWorkclawConfig)
+ * @param agentId - Target agent ID (optional)
+ * @param pluginRuntime - OpenClaw plugin runtime (optional, enables full session handling)
+ * @param recordSession - Whether to record session (default true)
+ * @param log 日志对象（可选）
+ * @param {Function} [log.info] - 信息日志函数
+ * @param {Function} [log.error] - 错误日志函数
+ * @param {Function} [log.warn] - 警告日志函数
+ */
+export async function buildInboundContext(
+  message: InboundMessage,
+  accountId: string,
+  config: any,
+  agentId?: string,
+  pluginRuntime?: PluginRuntime,
+  recordSession: boolean = true,
+  log?: { info?: (msg: string) => void, warn?: (msg: string) => void, error?: (msg: string) => void },
+): Promise<InboundContextPayload> {
+  // 尝试从 rawPayload 中提取已有的 sessionKey（新建话题时 openclaw 会生成新的 session）
+  let existingSessionKey: string | undefined
+  try {
+    const rawPayload = JSON.parse(message.rawPayload)
+    existingSessionKey = rawPayload.sessionKey
+  }
+  catch {
+    // ignore
+  }
+
+  const peerId = message.from
+  const computedSessionKey = existingSessionKey
+    || (agentId && agentId !== 'main'
+      ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
+      : undefined)
+
+  const sessionKey = computedSessionKey || (agentId && agentId !== 'main'
+    ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
+    : undefined)
+
+  // Basic context (used as base for both paths)
+  const result: InboundContextPayload = {
+    Body: message.text,
+    BodyForAgent: message.rawPayload || message.text,
+    RawBody: JSON.stringify(message),
+    From: message.from,
+    To: message.to,
+    ChatType: message.chatType,
+    Provider: OPENCLAW_WORKCLAW_CHANNEL,
+    Surface: OPENCLAW_WORKCLAW_CHANNEL,
+    Timestamp: message.timestamp,
+    AccountId: accountId,
+    AgentId: agentId,
+    MessageSid: message.messageId,
+    OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
+    OriginatingTo: message.to,
+  }
+
+  if (sessionKey) {
+    result.SessionKey = sessionKey
+  }
+
+  // If no pluginRuntime provided, return basic context without session recording
+  if (!pluginRuntime) {
+    return result
+  }
+
+  // Full session handling path
+  const storePath = pluginRuntime.channel.session.resolveStorePath(config.session?.store, { agentId })
+  log?.info?.(`[Session] storePath=${storePath}, agentId=${agentId}, sessionKey=${sessionKey}`)
+
+  // 获取 envelope 格式选项
+  const envelopeOptions = pluginRuntime.channel.reply.resolveEnvelopeFormatOptions(config)
+
+  // 获取上次的 session 更新时间
+  const previousTimestamp = pluginRuntime.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: sessionKey!,
+  })
+  log?.info?.(`[Session] previousTimestamp=${previousTimestamp}`)
+
+  // 格式化 envelope（Body 用于日志/历史，BodyForAgent 用于 AI）
+  const fromLabel = message.to
+  const body = pluginRuntime.channel.reply.formatInboundEnvelope({
+    channel: OPENCLAW_WORKCLAW_CHANNEL,
+    from: fromLabel,
+    timestamp: message.timestamp,
+    body: message.text,
+    chatType: message.chatType,
+    sender: { name: message.to, id: message.to },
+    previousTimestamp,
+    envelope: envelopeOptions,
+  })
+
+  // 构建完整的 ctx
+  const finalized = pluginRuntime.channel.reply.finalizeInboundContext({
+    Body: body,
+    BodyForAgent: message.text,
+    RawBody: JSON.stringify(message),
+    CommandBody: message.text,
+    From: message.from,
+    To: message.to,
+    SessionKey: sessionKey,
+    AccountId: accountId,
+    ChatType: message.chatType,
+    ConversationLabel: fromLabel,
+    Provider: OPENCLAW_WORKCLAW_CHANNEL,
+    Surface: 'openclaw-workclaw_dm',
+    MessageSid: message.messageId,
+    Timestamp: message.timestamp,
+    OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
+    OriginatingTo: message.to,
+  })
+
+  // 记录 session（需要在 dispatchReplyWithBufferedBlockDispatcher 之前调用）
+  // 这样 OpenClaw 才能在工具执行时正确关联 session
+  if (sessionKey && recordSession) {
+    try {
+      await pluginRuntime.channel.session.recordInboundSession({
+        storePath,
+        sessionKey: finalized.SessionKey || sessionKey,
+        ctx: finalized,
+        updateLastRoute: {
+          sessionKey,
+          channel: OPENCLAW_WORKCLAW_CHANNEL,
+          to: message.to,
+          accountId,
+        },
+        onRecordError: (err: unknown) => {
+          log?.error?.(`[Session] recordInboundSession failed: ${String(err)}`)
+        },
+      })
+      log?.info?.(`[Session] Recorded session for key=${sessionKey}`)
+    }
+    catch (err) {
+      log?.warn?.(`[Session] recordInboundSession error: ${String(err)}`)
+    }
+  }
+
+  return finalized
+}