多 Agent 协同模式：Router 路由分发、Supervisor 主从编排与 Handoff 交接

                       ┌──► [Coder Agent]   (独立上下文 + 文件/AST 工具) ──► 仅返回补丁摘要
[Supervisor 主控 Agent] ┼──► [Tester Agent]  (独立上下文 + 单测沙箱工具) ──► 仅返回测试报告
                       └──► [SecOps Agent]  (独立上下文 + 漏洞扫描工具) ──► 仅返回审计结论

export class MultiAgentSwarm {
  constructor({ llm, maxHandoffs = 6 }) {
    this.llm = llm
    this.agents = new Map() // agentName -> { name, rolePrompt, registry }
    this.maxHandoffs = maxHandoffs
  }

  registerAgent({ name, description, rolePrompt, registry }) {
    this.agents.set(name, { name, description, rolePrompt, registry })
    return this
  }

  // 为当前激活的 Agent 动态注入「交接给其他专职 Agent」的虚拟 Handoff 工具
  #buildToolsWithHandoffs(currentAgentName) {
    const current = this.agents.get(currentAgentName)
    const baseTools = current.registry ? current.registry.toOpenAiTools() : []

    const peerNames = [...this.agents.keys()].filter((n) => n !== currentAgentName)
    if (peerNames.length === 0) return baseTools

    const peerDesc = peerNames
      .map((n) => `${n}: ${this.agents.get(n).description}`)
      .join('；')

    return [
      ...baseTools,
      {
        type: 'function',
        function: {
          name: 'delegate_to_agent',
          description: `将子任务委派或交接给更专业的同伴 Agent。可选目标：${peerDesc}`,
          parameters: {
            type: 'object',
            properties: {
              targetAgent: { type: 'string', enum: peerNames },
              subtaskBrief: { type: 'string', description: '清晰、自包含的子任务说明与已掌握的关键上下文' }
            },
            required: ['targetAgent', 'subtaskBrief']
          }
        }
      }
    ]
  }

  // 在独立隔离的临时上下文中运行指定子 Agent，仅向上游返回最终摘要结论
  async runIsolatedSubagent(agentName, subtaskBrief, depth = 0) {
    if (depth > this.maxHandoffs) {
      return `委派深度超出上限 (${this.maxHandoffs})，已终止交接。`
    }
    const agent = this.agents.get(agentName)
    if (!agent) throw new Error(`未找到目标 Agent: ${agentName}`)

    const subMessages = [
      { role: 'system', content: agent.rolePrompt },
      { role: 'user', content: subtaskBrief }
    ]

    for (let step = 1; step <= 6; step++) {
      const res = await this.llm.chat({
        messages: subMessages,
        tools: this.#buildToolsWithHandoffs(agentName)
      })
      const msg = res.message
      subMessages.push(msg)

      if (!msg.tool_calls || msg.tool_calls.length === 0) {
        return msg.content || ''
      }

      for (const tc of msg.tool_calls) {
        if (tc.function.name === 'delegate_to_agent') {
          const { targetAgent, subtaskBrief: nextBrief } = JSON.parse(tc.function.arguments || '{}')
          const subResult = await this.runIsolatedSubagent(targetAgent, nextBrief, depth + 1)
          subMessages.push({
            role: 'tool',
            tool_call_id: tc.id,
            name: 'delegate_to_agent',
            content: JSON.stringify({ delegatedTo: targetAgent, summary: subResult })
          })
        } else {
          const toolMsg = await agent.registry.invokeOne(tc)
          subMessages.push(toolMsg)
        }
      }
    }

    return subMessages.at(-1)?.content || '子任务已执行完毕'
  }
}