@dcrays/dcgchat 0.3.35 → 0.4.4

package/src/channel.ts

@@ -1,13 +1,61 @@
-import type { ChannelPlugin, OpenClawConfig } from 'openclaw/plugin-sdk'
-import { DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk'
+import type { ChannelPlugin, OpenClawConfig, PluginRuntime } from 'openclaw/plugin-sdk'
+import { createPluginRuntimeStore, DEFAULT_ACCOUNT_ID } from 'openclaw/plugin-sdk'
 import type { ResolvedDcgchatAccount, DcgchatConfig } from './types.js'
 import { ossUpload } from './request/oss.js'
-import { addSentMediaKey, getCronMessageId, getInfoBySessionKey, getOpenClawConfig, hasSentMediaKey } from './utils/global.js'
+import {
+  addSentMediaKey,
+  getCronMessageId,
+  getDcgchatRuntime,
+  getInfoBySessionKey,
+  getOpenClawConfig,
+  hasSentMediaKey
+} from './utils/global.js'
 import { isWsOpen, mergeDefaultParams, mergeSessionParams, sendFinal, wsSendRaw } from './transport.js'
 import { dcgLogger, setLogger } from './utils/log.js'
 import { getOutboundMsgParams, getParamsMessage } from './utils/params.js'
 import { startDcgchatGatewaySocket } from './gateway/socket.js'
 
+function dcgchatChannelCfg(): DcgchatConfig {
+  return (getOpenClawConfig()?.channels?.["dcgchat"] as DcgchatConfig | undefined) ?? {}
+}
+
+/** `agent:<code>:mobook:direct:<agentId>:<sessionId>`（与 getSessionKey 非 real_mobook 分支一致） */
+function isMobookDirectSessionKey(s: string): boolean {
+  const parts = s.split(':').filter((p) => p.length > 0)
+  const low = parts.map((p) => p.toLowerCase())
+  return parts.length >= 6 && low[0] === 'agent' && low[2] === 'mobook' && low[3] === 'direct'
+}
+
+/** real_mobook 等线路下 Core 分配的 `agent:<agentId>:…` sessionKey */
+function isAgentPrefixedSessionKey(s: string): boolean {
+  const parts = s.split(':').filter((p) => p.length > 0)
+  return parts.length >= 3 && parts[0].toLowerCase() === 'agent'
+}
+
+/**
+ * 供 `messaging.targetResolver.looksLikeId` 使用：与 OpenClaw `resolveMessagingTarget` 对齐，
+ * 仅当 target「像合法会话路由键」时才走 id 类解析；纯数字不会命中，从而在系统层拒绝误填 userId。
+ */
+function looksLikeDcgchatMessageToolTarget(raw: string): boolean {
+  let s = raw.trim()
+  if (!s) return false
+  const prefix = 'dcg-cron:'
+  if (s.startsWith(prefix)) {
+    s = s.slice(prefix.length).trim()
+    if (!s) return false
+  }
+  if (isMobookDirectSessionKey(s)) return true
+  if (isAgentPrefixedSessionKey(s)) return true
+  return false
+}
+
+function dcgchatMessageTargetLooksLikeId(raw: string, _normalized?: string): boolean {
+  if (dcgchatChannelCfg().strictMessageToolTarget === false) {
+    return Boolean(raw?.trim())
+  }
+  return looksLikeDcgchatMessageToolTarget(raw)
+}
+
 export type DcgchatMediaSendOptions = {
   /** 与 setParamsMessage / map 一致，用于 getOutboundMsgParams */
   sessionKey: string
@@ -98,7 +146,8 @@ export const dcgchatPlugin: ChannelPlugin<ResolvedDcgchatAccount> = {
     effects: true
     // blockStreaming: true,
   },
-  reload: { configPrefixes: ['channels.dcgchat'] },
+  /** 当前构建的 channel id + 兼容旧配置键 `channels.dcgchat` */
+  reload: { configPrefixes: [`channels.${"dcgchat"}`, 'channels.dcgchat'] },
   configSchema: {
     schema: {
       type: 'object',
@@ -107,16 +156,25 @@ export const dcgchatPlugin: ChannelPlugin<ResolvedDcgchatAccount> = {
         enabled: { type: 'boolean' },
         wsUrl: { type: 'string' },
         botToken: { type: 'string' },
-        userId: { type: 'string', description: 'WebSocket 连接参数 _userId，与 message 工具的 target（effectiveSessionKey）无关' },
+        userId: { type: 'string', description: 'WebSocket 连接参数 _userId，与 dcgchat_message 工具的 target（dcgSessionKey）无关' },
         appId: { type: 'string' },
         domainId: { type: 'string' },
-        capabilities: { type: 'array', items: { type: 'string' } }
+        capabilities: { type: 'array', items: { type: 'string' } },
+        strictMessageToolTarget: {
+          type: 'boolean',
+          description:
+            '默认 true：内置 message 工具的 target 须为 sessionKey 形态（如 agent:…:mobook:direct:… 或 agent: 前缀多段），禁止纯数字 WS userId。设为 false 关闭此校验。'
+        }
       }
     },
     uiHints: {
       userId: {
         label: 'WS 连接 _userId',
-        help: '仅用于拼接网关 WebSocket URL 的查询参数，不是 Agent 发消息时的 target。发消息请使用 effectiveSessionKey（与入站上下文 SessionKey 相同，格式如 agent:main:mobook:direct:…）。'
+        help: '仅用于拼接网关 WebSocket URL 的查询参数，不是 Agent 发消息时的 target。发消息请使用 dcgSessionKey（与入站上下文 SessionKey 相同）。'
+      },
+      strictMessageToolTarget: {
+        label: '严格 message.target',
+        help: '开启后由通道目标解析层拒绝纯数字等非 sessionKey 的 target（推荐开启）；关闭则与旧版行为一致。'
       }
     }
   },
@@ -124,16 +182,17 @@ export const dcgchatPlugin: ChannelPlugin<ResolvedDcgchatAccount> = {
     listAccountIds: () => [DEFAULT_ACCOUNT_ID],
     resolveAccount: (cfg, accountId) => resolveAccount(cfg, accountId),
     defaultAccountId: () => DEFAULT_ACCOUNT_ID,
-    setAccountEnabled: ({ cfg, enabled }) => ({
-      ...cfg,
-      channels: {
-        ...cfg.channels,
-        dcgchat: {
-          ...(cfg.channels?.["dcgchat"] as Record<string, unknown> | undefined),
-          enabled
+    setAccountEnabled: ({ cfg, enabled }) => {
+      const channelKey = "dcgchat"
+      const prev = (cfg.channels?.[channelKey as keyof NonNullable<typeof cfg.channels>] as Record<string, unknown> | undefined) ?? {}
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          [channelKey]: { ...prev, enabled }
         }
       }
-    }),
+    },
     isConfigured: (account) => account.configured,
     describeAccount: (account) => ({
       accountId: account.accountId,
@@ -149,14 +208,26 @@ export const dcgchatPlugin: ChannelPlugin<ResolvedDcgchatAccount> = {
   messaging: {
     normalizeTarget: (raw) => raw || undefined,
     targetResolver: {
-      looksLikeId: (raw) => Boolean(raw?.trim()),
-      hint: 'effectiveSessionKey（与 SessionKey 一致；勿填配置里的 WS userId）'
+      looksLikeId: dcgchatMessageTargetLooksLikeId,
+      hint: '须为完整 dcgSessionKey（与 SessionKey 一致，形如 agent:…:mobook:direct:… 或 agent: 前缀路由键）；禁止填 WS userId 等纯数字。可在通道配置 strictMessageToolTarget=false 关闭校验。'
     }
   },
+  /**
+   * 与 Telegram 等通道一致：用入站路由键 `To`（即 SessionKey / OriginatingTo）作为 message 工具默认 `currentChannelId`。
+   * 显式 target 由 `messaging.targetResolver.looksLikeId` + OpenClaw `resolveMessagingTarget` 校验（见 strictMessageToolTarget）。
+   */
+  threading: {
+    buildToolContext: ({ context, hasRepliedRef }) => ({
+      currentChannelId: context.To?.trim() || undefined,
+      hasRepliedRef
+    })
+  },
   agentPrompt: {
     messageToolHints: () => [
-      '书灵墨宝：message 工具的 target 必须填 effectiveSessionKey（与当前会话 SessionKey / OriginatingTo 相同），形如 agent:main:mobook:direct:<agent_id>:<session_id>；不要填 channels.dcgchat.userId 或纯数字 userId。',
-      'OpenClaw 自带的 target 字段说明里仍可能出现 “user id”，在本频道请忽略该字样，一律按 effectiveSessionKey 理解。'
+      '生成文件后，**尽可能不要**把文件路径、地址直接告诉用户。',
+      '生成文件后，把文件名告诉用户。',
+      '使用内置 `message` 或 `dcgchat_message` 发消息时，target 必须是完整 dcgSessionKey（与上下文 SessionKey 相同），禁止填 From、SenderId、WS userId 等纯数字。',
+      '生成文件后，须通过工具发送文件，勿在文本里直接输出路径或地址。'
     ]
   },
   outbound: {
@@ -167,6 +238,7 @@ export const dcgchatPlugin: ChannelPlugin<ResolvedDcgchatAccount> = {
       }
       return { ok: true, to: to }
     },
+    chunker: (text, limit) => getDcgchatRuntime().channel.text.chunkMarkdownText(text, limit),
     textChunkLimit: 4000,
     sendText: async (ctx) => {
       dcgLogger(`channel sendText to ${ctx.to} `)

package/src/cron.ts

@@ -40,11 +40,6 @@ export function readCronJob(jobPath: string, jobId: string): Record<string, any>
   }
 }
 
-function msgParamsToCtx(p: IMsgParams): IMsgParams | null {
-  if (!p?.botToken) return null
-  return p
-}
-
 const CRON_UPLOAD_DEBOUNCE_MS = 2400
 
 let cronUploadFlushTimer: ReturnType<typeof setTimeout> | null = null
@@ -63,9 +58,10 @@ async function runCronJobsUpload(sessionKey: string): Promise<void> {
         event_type: 'cron',
         operation_type: 'install',
         session_id: sessionId,
-        agent_id: agentId
+        agent_id: agentId,
+        oss_url: url
       }
-      sendEventMessage(url, params)
+      sendEventMessage(params)
     } catch (error) {
       dcgLogger(`${jobPath} upload failed: ${error}`, 'error')
     }
@@ -170,6 +166,7 @@ export const finishedDcgchatCron = async (jobId: string) => {
     sendFinal(merged, 'cron send')
   }
   const ws = getWsConnection()
+  const baseContent = getParamsDefaults()
   if (isWsOpen()) {
     ws?.send(
       JSON.stringify({
@@ -178,15 +175,17 @@ export const finishedDcgchatCron = async (jobId: string) => {
         content: {
           event_type: 'notify',
           operation_type: 'cron',
+          bot_token: baseContent.botToken,
+          app_id: baseContent.appId,
           session_id: sessionId,
-          agentId: agentId,
+          agent_id: agentId,
           real_mobook: !sessionId ? 1 : '',
           title: name
         }
       })
     )
-    dcgLogger(`定时任务执行成功: ${id}`)
   }
+  dcgLogger(`定时任务执行成功: ${id}`)
   removeCronMessageId(sessionKey)
   dcgLogger(`finishedDcgchatCron: job=${id} sessionKey=${sessionKey}`)
 }

package/src/gateway/index.ts

@@ -3,8 +3,8 @@ import { WebSocket } from 'ws'
 import crypto from 'crypto'
 import { deriveDeviceIdFromPublicKey, publicKeyRawBase64UrlFromPem, buildDeviceAuthPayloadV3, signDevicePayload } from './security.js'
 import { dcgLogger } from '../utils/log.js'
-import { finishedDcgchatCron, sendDcgchatCron } from '../cron.js'
 import { getWorkspaceDir } from '../utils/global.js'
+import { handleGatewayEventMessage } from '../utils/gatewayMsgHanlder.js'
 
 export interface GatewayEvent {
   type: string
@@ -358,31 +358,7 @@ export class GatewayConnection {
     }
 
     if (msg.type === 'event') {
-      try {
-        // 定时任务相关事件
-        if (msg.event === 'cron') {
-          dcgLogger(`[Gateway] 收到事件: ${JSON.stringify(msg)}`)
-          if (msg.payload?.action === 'added') {
-            sendDcgchatCron(msg.payload?.jobId)
-          }
-          if (msg.payload?.action === 'updated') {
-            sendDcgchatCron(msg.payload?.jobId as string)
-          }
-          if (msg.payload?.action === 'removed') {
-            sendDcgchatCron(msg.payload?.jobId as string)
-          }
-          if (msg.payload?.action === 'finished') {
-            finishedDcgchatCron(msg.payload?.jobId as string)
-          }
-        }
-      } catch (error) {
-        dcgLogger(`[Gateway] 处理事件失败: ${error}`, 'error')
-      }
-      const event: GatewayEvent = {
-        type: msg.event as string,
-        payload: msg.payload as Record<string, unknown> | undefined,
-        seq: msg.seq as number | undefined
-      }
+      const event = handleGatewayEventMessage(msg)
       this.eventHandlers.forEach((h) => h(event))
     }
   }

package/src/gateway/socket.ts

@@ -212,7 +212,7 @@ async function connectPersistentGateway(): Promise<void> {
     startPingTimer(gw)
     dcgLogger(`Gateway 持久连接成功 connId=${gw.getConnId() ?? '?'}`)
   } catch (e) {
-    dcgLogger(`Gateway 连接失败11: ${e}`, 'error')
+    dcgLogger(`Gateway 连接失败: ${e}`, 'error')
     persistentConn = null
     clearPingTimer()
     if (!socketStopped) {
@@ -230,8 +230,10 @@ export function startDcgchatGatewaySocket(): void {
   socketStopped = false
   clearReconnectTimer()
   if (startupConnectTimer != null) return
-  startupConnectTimer = null
-  void connectPersistentGateway()
+  startupConnectTimer = setTimeout(() => {
+    startupConnectTimer = null
+    void connectPersistentGateway()
+  }, 0)
 }
 
 /**

package/src/monitor.ts

@@ -1,15 +1,10 @@
 import type { ClawdbotConfig, RuntimeEnv } from 'openclaw/plugin-sdk'
 import WebSocket from 'ws'
-import { handleDcgchatMessage } from './bot.js'
 import { resolveAccount } from './channel.js'
-import { setWsConnection, getOpenClawConfig, setMsgStatus, getSessionKey } from './utils/global.js'
-import type { InboundMessage } from './types.js'
-import { installSkill, uninstallSkill } from './skill.js'
+import { setWsConnection, getOpenClawConfig } from './utils/global.js'
 import { dcgLogger } from './utils/log.js'
-import { onDisabledCronJob, onEnabledCronJob, onRemoveCronJob, onRunCronJob } from './cron.js'
-import { ignoreToolCommand } from './utils/constant.js'
 import { isWsOpen } from './transport.js'
-import { onRemoveSession } from './session.js'
+import { handleParsedWsMessage } from './utils/wsMessageHandler.js'
 
 export type MonitorDcgchatOpts = {
   config?: ClawdbotConfig
@@ -128,51 +123,7 @@ export async function monitorDcgchatProvider(opts: MonitorDcgchatOpts): Promise<
         dcgLogger(`用户消息content字段解析失败: invalid JSON received`, 'error')
         return
       }
-
-      if (parsed.messageType == 'openclaw_bot_chat') {
-        const msg = parsed as unknown as InboundMessage
-        // 与 monitor 原逻辑一致：工具类指令不进入 running，避免误触工具链监控
-        const effectiveSessionKey = getSessionKey(msg.content, account.accountId)
-        if (!ignoreToolCommand.includes(msg.content.text?.trim() ?? '')) {
-          setMsgStatus(effectiveSessionKey, 'running')
-        } else {
-          setMsgStatus(effectiveSessionKey, 'finished')
-        }
-        await handleDcgchatMessage(msg, account.accountId)
-      } else if (parsed.messageType == 'openclaw_bot_event') {
-        const { event_type, operation_type } = parsed.content ? parsed.content : ({} as Record<string, any>)
-        if (event_type === 'skill') {
-          const { skill_url, skill_code, skill_id, bot_token, websocket_trace_id } = parsed.content
-          const content = { event_type, operation_type, skill_url, skill_code, skill_id, bot_token, websocket_trace_id }
-          if (operation_type === 'install' || operation_type === 'enable' || operation_type === 'update') {
-            installSkill({ path: skill_url, code: skill_code }, content)
-          } else if (operation_type === 'remove' || operation_type === 'disable') {
-            uninstallSkill({ code: skill_code }, content)
-          } else {
-            dcgLogger(`openclaw_bot_event unknown event_type: ${event_type}, ${data.toString()}`)
-          }
-        } else if (event_type === 'cron') {
-          const { job_id, message_id } = parsed.content
-          if (operation_type === 'remove') {
-            await onRemoveCronJob(job_id)
-          } else if (operation_type === 'enable') {
-            await onEnabledCronJob(job_id)
-          } else if (operation_type === 'disable') {
-            await onDisabledCronJob(job_id)
-          } else if (operation_type === 'run') {
-            await onRunCronJob(job_id, message_id)
-          }
-        } else if (event_type === 'session') {
-          const { agent_id, session_id, agent_clone_code } = parsed.content
-          if (operation_type === 'remove') {
-            await onRemoveSession({ agent_id, session_id, agent_clone_code, account_id: accountId })
-          }
-        } else {
-          dcgLogger(`openclaw_bot_event unknown operation_type: ${operation_type}, ${data.toString()}`)
-        }
-      } else {
-        dcgLogger(`ignoring unknown messageType: ${parsed.messageType}`, 'error')
-      }
+      await handleParsedWsMessage(parsed, payloadStr, account.accountId)
     })
 
     ws.on('close', (code, reason) => {

package/src/session.ts

@@ -6,11 +6,11 @@ interface TSession {
   agent_id: string
   session_id: string
   agent_clone_code?: string
-  account_id?: string
+  account_id: string
 }
 
 export const onRemoveSession = async ({ agent_id, session_id, agent_clone_code, account_id }: TSession) => {
-  const sessionKey = getSessionKey({ agent_id, session_id }, account_id)
+  const sessionKey = getSessionKey({ agent_id, session_id, agent_clone_code }, account_id)
   if (!session_id) {
     dcgLogger('onRemoveSession: empty session_id', 'error')
     return

package/src/tool.ts

@@ -2,7 +2,7 @@ import type { OpenClawPluginApi } from 'openclaw/plugin-sdk'
 import { getMsgStatus } from './utils/global.js'
 import { dcgLogger } from './utils/log.js'
 import { sendFinal, sendText, wsSendRaw } from './transport.js'
-import { getEffectiveMsgParams } from './utils/params.js'
+import { getEffectiveMsgParams, deleteSessionKeyBySubAgentRunId, setSessionKeyBySubAgentRunId } from './utils/params.js'
 import { cronToolCall } from './cronToolCall.js'
 
 type PluginHookName =
@@ -68,10 +68,243 @@ interface CronDelivery {
   [key: string]: unknown
 }
 
+// --- Subagent 活跃跟踪（按主会话 requesterSessionKey）---
+
+/** 主会话 sessionKey -> 仍活跃的子 agent runId */
+const activeSubagentRunIdsByRequester = new Map<string, Set<string>>()
+/** 子会话 childSessionKey -> 主会话 requesterSessionKey */
+const requesterByChildSessionKey = new Map<string, string>()
+/** 子会话 childSessionKey -> spawn 时的 runId（ended 事件可能不带 runId） */
+const runIdByChildSessionKey = new Map<string, string>()
+/** 主会话 -> 等待「子 agent 全部结束」的回调 */
+const subagentIdleWaiters = new Map<string, Set<() => void>>()
+
+function getOrCreateRunIdSet(requesterSessionKey: string): Set<string> {
+  let set = activeSubagentRunIdsByRequester.get(requesterSessionKey)
+  if (!set) {
+    set = new Set()
+    activeSubagentRunIdsByRequester.set(requesterSessionKey, set)
+  }
+  return set
+}
+
+function flushSubagentIdleWaiters(requesterSessionKey: string): void {
+  const set = activeSubagentRunIdsByRequester.get(requesterSessionKey)
+  if (set && set.size > 0) return
+  activeSubagentRunIdsByRequester.delete(requesterSessionKey)
+  const waiters = subagentIdleWaiters.get(requesterSessionKey)
+  if (!waiters?.size) return
+  subagentIdleWaiters.delete(requesterSessionKey)
+  for (const w of waiters) {
+    try {
+      w()
+    } catch (e) {
+      dcgLogger(`subagent idle waiter error: ${String(e)}`, 'error')
+    }
+  }
+}
+
+function registerSubagentSpawn(requesterSessionKey: string, runId: string, childSessionKey: string): void {
+  const req = requesterSessionKey.trim()
+  const rid = runId.trim()
+  const child = childSessionKey.trim()
+  if (!req || !rid || !child) {
+    dcgLogger(`subagent track spawn skipped: missing key req=${req} runId=${rid} child=${child}`)
+    return
+  }
+  getOrCreateRunIdSet(req).add(rid)
+  requesterByChildSessionKey.set(child, req)
+  runIdByChildSessionKey.set(child, rid)
+  dcgLogger(`subagent track spawn: requester=${req} runId=${rid} child=${child} active=${getOrCreateRunIdSet(req).size}`)
+}
+
+function registerSubagentEnd(
+  ctx: { requesterSessionKey?: string; sessionKey?: string },
+  targetSessionKey: string,
+  runId?: string
+): void {
+  const child = targetSessionKey.trim()
+  if (!child) return
+  const req = ctx.requesterSessionKey?.trim() || requesterByChildSessionKey.get(child) || ctx.sessionKey?.trim() || ''
+  const resolvedRunId = (runId?.trim() || runIdByChildSessionKey.get(child) || '').trim()
+  deleteSessionKeyBySubAgentRunId(resolvedRunId)
+  if (!req) {
+    dcgLogger(`subagent track end: no requester for child=${child} runId=${resolvedRunId}`)
+    requesterByChildSessionKey.delete(child)
+    runIdByChildSessionKey.delete(child)
+    return
+  }
+  const set = activeSubagentRunIdsByRequester.get(req)
+  if (set && resolvedRunId) {
+    set.delete(resolvedRunId)
+  }
+  requesterByChildSessionKey.delete(child)
+  runIdByChildSessionKey.delete(child)
+  dcgLogger(`subagent track end: requester=${req} runId=${resolvedRunId || 'n/a'} remaining=${set?.size ?? 0}`)
+  if (set && set.size === 0) {
+    activeSubagentRunIdsByRequester.delete(req)
+  }
+  flushSubagentIdleWaiters(req)
+}
+
+/** 当前跟踪到的、挂在该主会话下的子会话 sessionKey（供 /stop 时逐个 chat.abort） */
+export function getChildSessionKeysTrackedForRequester(requesterSessionKey: string): string[] {
+  const req = requesterSessionKey.trim()
+  if (!req) return []
+  const out: string[] = []
+  for (const [child, parent] of requesterByChildSessionKey.entries()) {
+    if (parent === req) out.push(child)
+  }
+  return out
+}
+
+/**
+ * 打断后清空本地子 agent 跟踪（runId、父子映射、子 runId→sessionKey），并唤醒 waitUntilSubagentsIdle，避免永久挂起。
+ */
+export function resetSubagentStateForRequesterSession(requesterSessionKey: string): void {
+  const req = requesterSessionKey.trim()
+  if (!req) return
+
+  const runIdSet = activeSubagentRunIdsByRequester.get(req)
+  if (runIdSet) {
+    for (const rid of runIdSet) {
+      deleteSessionKeyBySubAgentRunId(rid)
+    }
+  }
+
+  for (const [child, parent] of [...requesterByChildSessionKey.entries()]) {
+    if (parent === req) {
+      requesterByChildSessionKey.delete(child)
+      runIdByChildSessionKey.delete(child)
+    }
+  }
+
+  activeSubagentRunIdsByRequester.delete(req)
+
+  const waiters = subagentIdleWaiters.get(req)
+  if (!waiters?.size) return
+  subagentIdleWaiters.delete(req)
+  for (const w of waiters) {
+    try {
+      w()
+    } catch (e) {
+      dcgLogger(`subagent idle waiter error: ${String(e)}`, 'error')
+    }
+  }
+}
+
+/** 当前主会话下仍在跑的子 agent 数量（按 spawn 时 runId 去重） */
+export function getActiveSubagentCount(sessionKey: string): number {
+  const sk = sessionKey?.trim()
+  if (!sk) return 0
+  return activeSubagentRunIdsByRequester.get(sk)?.size ?? 0
+}
+
+/**
+ * 等到指定主会话下已跟踪的子 agent 全部结束（spawn 失败等路径也会触发 subagent_ended，一般会配对清理）。
+ * 注意：须在收到 `subagent_spawned` 之后才会计入；仅 spawning 未 spawned 的不会阻塞。
+ */
+export function waitUntilSubagentsIdle(sessionKey: string, opts?: { timeoutMs?: number; signal?: AbortSignal }): Promise<void> {
+  const sk = sessionKey?.trim()
+  if (!sk) return Promise.resolve()
+
+  if (getActiveSubagentCount(sk) === 0) return Promise.resolve()
+
+  return new Promise<void>((resolve, reject) => {
+    let settled = false
+    const finish = (fn: () => void) => {
+      if (settled) return
+      settled = true
+      if (timeoutId) clearTimeout(timeoutId)
+      opts?.signal?.removeEventListener('abort', onAbort)
+      removeWaiter()
+      fn()
+    }
+
+    const removeWaiter = () => {
+      const bucket = subagentIdleWaiters.get(sk)
+      if (!bucket) return
+      bucket.delete(onIdle)
+      if (bucket.size === 0) subagentIdleWaiters.delete(sk)
+    }
+
+    const onIdle = () => finish(() => resolve())
+
+    const onAbort = () => {
+      const reason = opts?.signal?.reason
+      finish(() => reject(reason instanceof Error ? reason : new Error(String(reason ?? 'Aborted'))))
+    }
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined
+    if (opts?.timeoutMs != null && opts.timeoutMs > 0) {
+      timeoutId = setTimeout(
+        () => finish(() => reject(new Error(`waitUntilSubagentsIdle timeout ${opts.timeoutMs}ms`))),
+        opts.timeoutMs
+      )
+    }
+
+    if (opts?.signal) {
+      if (opts.signal.aborted) {
+        onAbort()
+        return
+      }
+      opts.signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    let set = subagentIdleWaiters.get(sk)
+    if (!set) {
+      set = new Set()
+      subagentIdleWaiters.set(sk, set)
+    }
+    set.add(onIdle)
+
+    if (getActiveSubagentCount(sk) === 0) {
+      onIdle()
+    }
+  })
+}
+
+function resolveHookSessionKey(
+  eventName: string,
+  args: { sessionKey?: string; requesterSessionKey?: string; runId?: string }
+): string {
+  if (
+    eventName === 'subagent_spawned' ||
+    eventName === 'subagent_ended' ||
+    eventName === 'subagent_spawning' ||
+    eventName === 'subagent_delivery_target'
+  ) {
+    if (args?.runId && args?.requesterSessionKey) setSessionKeyBySubAgentRunId(args?.runId, args?.requesterSessionKey)
+    return (args?.requesterSessionKey || args?.sessionKey || '').trim()
+  }
+  return (args?.sessionKey || '').trim()
+}
+
+function trackSubagentLifecycle(eventName: string, event: any, args: any): void {
+  if (eventName === 'subagent_spawned') {
+    const runId = typeof event?.runId === 'string' ? event.runId : ''
+    const childSessionKey = typeof event?.childSessionKey === 'string' ? event.childSessionKey : ''
+    const requester =
+      typeof args?.requesterSessionKey === 'string'
+        ? args.requesterSessionKey
+        : typeof args?.sessionKey === 'string'
+          ? args.sessionKey
+          : ''
+    registerSubagentSpawn(requester, runId, childSessionKey)
+    return
+  }
+  if (eventName === 'subagent_ended') {
+    const targetSessionKey = typeof event?.targetSessionKey === 'string' ? event.targetSessionKey : ''
+    const runId = typeof event?.runId === 'string' ? event.runId : undefined
+    registerSubagentEnd(args ?? {}, targetSessionKey, runId)
+  }
+}
+
 export function monitoringToolMessage(api: OpenClawPluginApi) {
   for (const item of eventList) {
     api.on(item.event as PluginHookName, (event: any, args: any) => {
-      const sk = args?.sessionKey as string
+      trackSubagentLifecycle(item.event, event, args)
+      const sk = resolveHookSessionKey(item.event, args ?? {})
       if (sk) {
         const status = getMsgStatus(sk)
         if (status === 'running') {
@@ -116,7 +349,7 @@ export function monitoringToolMessage(api: OpenClawPluginApi) {
             dcgLogger(`工具调用结果： ~ event:${item.event} ${status}`)
           }
         }
-      } else {
+      } else if (item.event !== 'before_tool_call') {
         dcgLogger(`工具调用结果： ~ event:${item.event} ~ 没有sessionKey 为执行`)
       }
     })