agentworkshop 0.2.1

package/server/services/workshop/runtime/channel-runtime.ts

@@ -0,0 +1,202 @@
+/**
+ * ChannelRuntime — Channel 隔离路由 + 订阅 + 广播 + 懒加载。
+ *
+ * route 仅在本 channel 内路由消息;订阅关系经 subscriptionRepo。
+ * 懒加载:agents map 不含目标时经 loader 回调按需装配(DB 行 → AgentRuntime);
+ */
+import { createLogger } from '../logger'
+import type { A2AMessage } from '../types/a2a'
+import type { SubscriptionRepo } from '../db/subscription.repo'
+import type { ChannelAgentRepo } from '../db/channel-agent.repo'
+import type { AgentRuntimeLike, TaskEngine } from './agent-runtime'
+
+const log = createLogger('workshop.channel')
+
+/** 调度循环结构契约(实现方 T5 SchedulerLoop) */
+export interface SchedulerLoopLike {
+  start(): void
+  wake(): void
+  stop(): void
+  setLoopResubmitCallback(fn: (title: string, description: string) => void): void
+}
+
+/** 懒加载器:按 agentId 装配 AgentRuntime(未找到/禁用返回 undefined);幂等 */
+export type AgentLoader = (agentId: string) => AgentRuntimeLike | undefined
+
+export class ChannelRuntime {
+  readonly channelId: string
+  private agents = new Map<string, AgentRuntimeLike>()
+  private schedulerLoop: SchedulerLoopLike | null = null
+  /** 懒加载回调(manager 注入);未装配的收件人经此按需 wire */
+  private loader: AgentLoader | null = null
+
+  constructor(
+    channelId: string,
+    private deps: { taskEngine: TaskEngine, subscriptionRepo: SubscriptionRepo, channelAgents: ChannelAgentRepo },
+    /** 路由成功回调(manager 注入:总线通知 → AEP a2a.message 帧 + 落库)。
+     *  经由本回调而非 manager.route 显式通知,是为了让调度器等直呼
+     *  channelRuntime.route 的调用方同样产生可见事件(催办消息不再对前端隐身)。 */
+    private onRouted: (message: A2AMessage) => void = () => {},
+  ) {
+    this.channelId = channelId
+  }
+
+  /** channel 全部 enabled 实例元信息(含未装配;供快照/调度看到完整团队) */
+  listChannelAgents(): Array<{ agentId: string, name: string, role: 'lead' | 'worker' }> {
+    return this.deps.channelAgents
+      .listByChannel(this.channelId)
+      .filter(m => m.enabled === 1)
+      .map(m => ({ agentId: m.id, name: m.name, role: m.role as 'lead' | 'worker' }))
+  }
+
+  setLoader(loader: AgentLoader): void {
+    this.loader = loader
+  }
+
+  /** 核心路由:解析收件人 → 按需装配 → 按优先级投递(immediate → injectSteer;task → mailbox) */
+  /**
+   * Channel 信箱路由(本 channel 内):垃圾守卫通过的消息统一落库到收件人
+   * mailbox(pending;lead 全览/断线重投/空闲回合作业都以此为准),
+   * 实时类消息(immediate 优先级,或带 in_reply_to 的回执)额外注入收件人
+   * 运行中的会话(steer 推送,送达即消费)——收件人忙则同轮可见,空闲则由
+   * 消费循环按 FIFO 起回合处理。
+   * 返回实际投递成功的收件人列表(发送方据此确认"真送达",不再静默丢失)。
+   */
+  route(message: A2AMessage): string[] {
+    if (!this.acceptByGuard(message)) return []
+    const meta = message.metadata ?? {}
+    const realtime
+      = meta['x-aw-msg-priority'] === 'immediate'
+        || typeof meta['x-aw-in-reply-to'] === 'string'
+    const delivered: string[] = []
+    for (const agentId of this.resolveRecipients(message)) {
+      const agent = this.ensureAgent(agentId)
+      if (!agent) continue
+      agent.enqueue(message)
+      delivered.push(agentId)
+      // 空闲收件人即时唤醒消费循环
+      if (agent.getState() === 'idle') agent.wakeMailbox()
+      if (realtime) agent.injectSteer(message)
+    }
+    // 实际投递成功的消息才通知总线(a2a.message 可见 + 落库);
+    // 守卫拦截/无收件人的消息不产生事件帧(时间线不出现幽灵消息)
+    if (delivered.length > 0) this.onRouted(message)
+    return delivered
+  }
+
+  /**
+   * 信箱守卫(垃圾信息拦截):三类消息放行,其余直接丢弃(不落库、不投递)——
+   *  ① 平台任务消息(task-kind + 真实存在的任务);
+   *  ② 声明发送人为本 channel 成员的消息(伪造/已移除成员 → 拒);
+   *  ③ 人类经 REST 注入的消息(x-aw-from-label 必须非空)。
+   * 防脏信息注入:无主消息与未知发送人的消息没有回执对象,处理它们只会
+   * 污染 Agent 上下文,因此拦截并删除。
+   */
+  private acceptByGuard(message: A2AMessage): boolean {
+    const meta = message.metadata ?? {}
+    const taskKind = meta['x-aw-task-kind']
+    if (taskKind !== undefined) {
+      const taskId = meta['x-aw-task-id']
+      if (typeof taskId === 'string' && this.deps.taskEngine.get(taskId)) return true
+      log.warn(`[ChannelRuntime:${this.channelId.slice(0, 8)}] 拦截无效任务消息(kind=${String(taskKind)} task=${String(taskId)}),已丢弃`)
+      return false
+    }
+    const from = meta['x-aw-from-agent']
+    if (typeof from === 'string' && from.length > 0) {
+      const member = this.deps.channelAgents.findByChannelAgent(this.channelId, from)
+      if (member && member.enabled === 1) return true
+      log.warn(`[ChannelRuntime:${this.channelId.slice(0, 8)}] 拦截非成员/已禁用成员消息(from=${from}),已丢弃`)
+      return false
+    }
+    const label = meta['x-aw-from-label']
+    if (typeof label === 'string' && label.length > 0) return true
+    log.warn(`[ChannelRuntime:${this.channelId.slice(0, 8)}] 拦截无发送人消息(target=${String(meta['x-aw-target-agent'] ?? '广播')}),已丢弃`)
+    return false
+  }
+
+  /** 按需装配 agent(loader 幂等);未装配成功返回 undefined */
+  private ensureAgent(agentId: string): AgentRuntimeLike | undefined {
+    let agent = this.agents.get(agentId)
+    if (!agent && this.loader) {
+      agent = this.loader(agentId)
+      if (agent) this.agents.set(agentId, agent)
+    }
+    return agent
+  }
+
+  /** 唤醒 agent(懒加载感知):未装配则先经 loader 装配再唤醒 */
+  wakeAgent(agentId: string): void {
+    this.ensureAgent(agentId)?.wakeMailbox()
+  }
+
+  addAgent(runtime: AgentRuntimeLike): void {
+    this.agents.set(runtime.agentId, runtime)
+  }
+
+  /** 永久移除(stop 运行时 + 移出 map;manager.removeAgent 用) */
+  async removeAgent(agentId: string): Promise<void> {
+    const runtime = this.agents.get(agentId)
+    if (runtime) {
+      await runtime.stop()
+      this.agents.delete(agentId)
+    }
+  }
+
+  /** 卸载移出(不停 stop;manager.unloadAgent 已 stop;仅删 map 引用) */
+  detachAgent(agentId: string): void {
+    this.agents.delete(agentId)
+  }
+
+  /** 解析目标 agentId 列表(规则见 §5.3;未装配收件人经 loader 按需装配) */
+  resolveRecipients(message: A2AMessage): string[] {
+    const meta = message.metadata ?? {}
+    // ① 点对点:x-aw-target-agent(同 channel 校验,目标不存在忽略)
+    const target = meta['x-aw-target-agent']
+    if (typeof target === 'string' && target.length > 0) {
+      return this.ensureAgent(target) ? [target] : []
+    }
+    // ② 任务消息:x-aw-task-kind 存在 → 直投 assignee(任务不存在忽略)
+    const taskKind = meta['x-aw-task-kind']
+    if (taskKind !== undefined) {
+      const taskId = meta['x-aw-task-id']
+      if (typeof taskId === 'string') {
+        const task = this.deps.taskEngine.get(taskId)
+        if (task && this.ensureAgent(task.assigneeId)) {
+          return [task.assigneeId]
+        }
+      }
+      return []
+    }
+    // ③ 无 target 普通消息:广播给订阅了发送者的 Agent;发送者 null 广播全部
+    const sender = meta['x-aw-from-agent']
+    if (sender == null) {
+      // 广播仅覆盖已装配的成员(不触发全量懒加载,避免广播唤醒整个 channel)
+      return [...this.agents.keys()]
+    }
+    return this.deps.subscriptionRepo
+      .listByTarget(this.channelId, sender as string)
+      .map(s => s.agentId)
+      .filter(id => this.ensureAgent(id) !== undefined)
+  }
+
+  getAgents(): AgentRuntimeLike[] {
+    return [...this.agents.values()]
+  }
+
+  get lead(): AgentRuntimeLike | null {
+    return this.getAgents().find(a => a.role === 'lead') ?? null
+  }
+
+  set scheduler(loop: SchedulerLoopLike | null) {
+    this.schedulerLoop = loop
+  }
+
+  get scheduler(): SchedulerLoopLike | null {
+    return this.schedulerLoop
+  }
+
+  /** 唤醒调度循环(事件驱动) */
+  wakeScheduler(): void {
+    this.schedulerLoop?.wake()
+  }
+}

package/server/services/workshop/runtime/embedding-provider.ts

@@ -0,0 +1,79 @@
+/**
+ * Embedding provider — OpenAI 兼容 /embeddings 端点(env 驱动,原生 fetch 零 SDK)。
+ * 未配置 env → 返回 null(向量分支整体关闭,记忆系统纯 FTS 降级)。
+ * 熔断:连续 3 次失败禁用 10 分钟(避免每个任务都白等超时)。
+ * 维度:首次成功 embed 的返回长度(不信任配置,以实测为准)。
+ */
+export interface EmbeddingProvider {
+  embed(texts: string[]): Promise<Float32Array[]>
+  /** 已知维度(首次成功 embed 前 null) */
+  dims(): number | null
+}
+
+const FAIL_THRESHOLD = 3
+const COOLDOWN_MS = 10 * 60_000
+const REQUEST_TIMEOUT_MS = 10_000
+
+export function createEnvEmbeddingProvider(): EmbeddingProvider | null {
+  const baseUrl = process.env.AW_MEMORY_EMBED_BASE_URL
+  const model = process.env.AW_MEMORY_EMBED_MODEL
+  if (!baseUrl || !model) return null
+  const apiKey = process.env.AW_MEMORY_EMBED_API_KEY ?? ''
+  let dims: number | null = null
+  let fails = 0
+  let disabledUntil = 0
+
+  return {
+    dims: () => dims,
+    async embed(texts: string[]): Promise<Float32Array[]> {
+      if (Date.now() < disabledUntil) throw new Error('embedding provider 冷却中')
+      let res: Response
+      try {
+        res = await fetch(`${baseUrl.replace(/\/$/, '')}/embeddings`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}) },
+          body: JSON.stringify({ input: texts, model }),
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        })
+      }
+      catch (err) {
+        // 网络层失败(拒绝连接/超时)同样计入熔断——超时是最常见失败形态
+        if (++fails >= FAIL_THRESHOLD) {
+          disabledUntil = Date.now() + COOLDOWN_MS
+          fails = 0
+        }
+        throw err
+      }
+      if (!res.ok) {
+        if (++fails >= FAIL_THRESHOLD) {
+          disabledUntil = Date.now() + COOLDOWN_MS
+          fails = 0
+        }
+        throw new Error(`embedding HTTP ${res.status}`)
+      }
+      const json = await res.json() as { data: Array<{ embedding: number[] }> }
+      dims = json.data[0]?.embedding.length ?? dims
+      fails = 0
+      return json.data.map(d => Float32Array.from(d.embedding))
+    },
+  }
+}
+
+/** 测试用确定性词袋 hash provider:相同词集 → 相近向量(零网络)。 */
+export function createHashEmbeddingProvider(dims: number): EmbeddingProvider {
+  return {
+    dims: () => dims,
+    async embed(texts: string[]): Promise<Float32Array[]> {
+      return texts.map((t) => {
+        const v = new Float32Array(dims)
+        for (const w of t.toLowerCase().split(/\s+/).filter(Boolean)) {
+          let h = 2166136261
+          for (let i = 0; i < w.length; i++) h = Math.imul(h ^ w.charCodeAt(i), 16777619)
+          v[Math.abs(h) % dims] = (v[Math.abs(h) % dims] ?? 0) + 1
+        }
+        const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0)) || 1
+        return v.map(x => x / norm) as Float32Array
+      })
+    },
+  }
+}

package/server/services/workshop/runtime/execution-mode.ts

@@ -0,0 +1,215 @@
+/**
+ * ExecutionMode 编排器 — goal / loop / pipeline 三种执行模式的核心调度逻辑。
+ *
+ * 模式语义:
+ *  - goal:     lead 接收目标 → 分解子任务给 worker → worker 完成 → lead 判断是否满足目标;
+ *              不满足则继续下发新任务;满足则完成主任务。核心:lead 的满意度判断。
+ *  - loop:     lead 按固定间隔(intervalMs)循环执行相同任务;每次循环:dispatch → worker 完成 →
+ *              等待 interval → 重新 dispatch。核心:定时循环重放。
+ *  - pipeline: lead 将任务分解为有序阶段(stages),每个阶段依赖前一阶段产出;
+ *              阶段 N 完成后 lead 将产出传递给阶段 N+1。核心:顺序依赖流。
+ *
+ * 模式信息存储:任务 metadata['x-aw-exec-mode'] + metadata['x-aw-mode-config']。
+ * SchedulerLoop 每轮 tick 时,ModeOrchestrator 根据 channel 当前任务的模式调整 lead 决策 prompt。
+ */
+import { randomUUID } from 'node:crypto'
+import type { ExecutionMode } from '../agents/agent-interface'
+import type { WorkspaceTask } from '../types/task'
+import type { A2AArtifact } from '../types/a2a'
+
+/** 模式配置(存储在任务 metadata['x-aw-mode-config']) */
+export interface ModeConfig {
+  /** loop: 循环间隔 ms(默认 60000;前端秒输入 ×1000,zod 下限 100) */
+  intervalMs?: number
+  /** loop: 最大循环次数(默认 Infinity) */
+  maxIterations?: number
+  /** pipeline: 阶段定义 */
+  stages?: PipelineStage[]
+  /** goal: 满意度判断提示(注入 lead prompt) */
+  goalCriteria?: string
+}
+
+/** pipeline 阶段定义 */
+export interface PipelineStage {
+  name: string
+  description: string
+  /** 分配给哪个 worker(agentId);省略则自动选空闲 worker */
+  assigneeId?: string
+}
+
+/** 模式元信息(从任务 metadata 提取) */
+export interface TaskModeInfo {
+  mode: ExecutionMode
+  config: ModeConfig
+}
+
+/** 从任务 metadata 提取模式信息 */
+export function extractTaskMode(task: WorkspaceTask): TaskModeInfo | null {
+  // 尝试从 history(初始 parts)或 description 中提取模式
+  // 模式信息存储在 metadata['x-aw-exec-mode'],但 WorkspaceTask 不直接暴露 metadata
+  // 这里通过任务 artifacts(初始 input)或 description 前缀来推断
+  const desc = task.description ?? ''
+  // 约定:description 以 [mode:xxx] 开头
+  const match = desc.match(/^\[mode:(goal|loop|pipeline)\]/)
+  if (match) {
+    const mode = match[1] as ExecutionMode
+    const config = parseModeConfig(desc, mode)
+    return { mode, config }
+  }
+  return null
+}
+
+/** 从 description 解析模式配置 */
+function parseModeConfig(desc: string, mode: ExecutionMode): ModeConfig {
+  const config: ModeConfig = {}
+  if (mode === 'loop') {
+    const intervalMatch = desc.match(/interval[:\s]+(\d+)/i)
+    config.intervalMs = intervalMatch ? parseInt(intervalMatch[1]!, 10) : 60_000
+    const maxMatch = desc.match(/max[:\s]+(\d+)/i)
+    config.maxIterations = maxMatch ? parseInt(maxMatch[1]!, 10) : Number.POSITIVE_INFINITY
+  }
+  if (mode === 'goal') {
+    // goalCriteria 从 description 中 [criteria:...] 提取
+    const criteriaMatch = desc.match(/\[criteria:([^\]]+)\]/)
+    config.goalCriteria = criteriaMatch?.[1]?.trim()
+  }
+  if (mode === 'pipeline') {
+    // 阶段名从 [stages:name1->name2] 提取(与 encodeTaskMode 编码格式对称)
+    const stagesMatch = desc.match(/\[stages:([^\]]+)\]/)
+    if (stagesMatch) {
+      config.stages = stagesMatch[1]!
+        .split('->')
+        .map(r => r.trim())
+        .filter(Boolean)
+        .map(name => ({ name, description: '' }))
+    }
+  }
+  return config
+}
+
+/** 将模式信息编码到 description 前缀 */
+export function encodeTaskMode(mode: ExecutionMode, config: ModeConfig, description: string): string {
+  const parts: string[] = [`[mode:${mode}]`]
+  if (mode === 'loop') {
+    const intervalMs = Math.min(86_400_000, Math.max(100, Math.floor(config.intervalMs ?? 60_000)))
+    parts.push(`[interval:${intervalMs}]`)
+    if (config.maxIterations !== undefined && config.maxIterations !== Number.POSITIVE_INFINITY) {
+      const maxIterations = Math.min(10_000, Math.max(1, Math.floor(config.maxIterations)))
+      parts.push(`[max:${maxIterations}]`)
+    }
+  }
+  if (mode === 'goal' && config.goalCriteria) {
+    parts.push(`[criteria:${config.goalCriteria}]`)
+  }
+  if (mode === 'pipeline' && config.stages) {
+    parts.push(`[stages:${config.stages.map(s => s.name).join('->')}]`)
+  }
+  return `${parts.join('')} ${description}`
+}
+
+/**
+ * Loop 控制器:管理 loop 模式的循环重放。
+ * 当主任务完成后,在 intervalMs 后重新创建相同任务。
+ */
+export class LoopController {
+  private iterations = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private active = true
+
+  constructor(
+    private readonly channelId: string,
+    private readonly taskTitle: string,
+    private readonly taskDescription: string,
+    private readonly intervalMs: number,
+    private readonly maxIterations: number,
+    private readonly onResubmit: (title: string, description: string) => void,
+  ) {}
+
+  /** 主任务完成时调用:启动下一轮倒计时 */
+  onTaskCompleted(): void {
+    this.iterations += 1
+    if (this.iterations >= this.maxIterations || !this.active) return
+    this.timer = setTimeout(() => {
+      if (!this.active) return
+      this.onResubmit(this.taskTitle, this.taskDescription)
+    }, this.intervalMs)
+  }
+
+  /** 停止循环 */
+  stop(): void {
+    this.active = false
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  /** 是否已达到最大迭代次数或已停止 */
+  get exhausted(): boolean {
+    return !this.active || this.iterations >= this.maxIterations
+  }
+
+  get currentIteration(): number {
+    return this.iterations
+  }
+}
+
+/**
+ * 检查 channel 中是否有处于特定模式的活跃任务。
+ * 返回第一个匹配的任务(通常 channel 同时只跑一个模式)。
+ */
+export function findModeTask(
+  tasks: WorkspaceTask[],
+  leadAgentId: string,
+): { task: WorkspaceTask, mode: ExecutionMode, config: ModeConfig } | null {
+  for (const task of tasks) {
+    if (task.assigneeId !== leadAgentId) continue
+    if (task.state === 'COMPLETED' || task.state === 'CANCELED' || task.state === 'FAILED') continue
+    const modeInfo = extractTaskMode(task)
+    if (modeInfo) {
+      return { task, mode: modeInfo.mode, config: modeInfo.config }
+    }
+  }
+  return null
+}
+
+/** goal-summary 完成标志判定:artifact 名称约定或正文含总结标头 */
+export function isGoalSummaryArtifact(a: A2AArtifact): boolean {
+  return a.name === 'goal-summary'
+    || a.parts.some(p => 'text' in p && p.text.includes('【目标完成总结】'))
+}
+
+/**
+ * goal 模式收口总结(「目标完成总结」结构化交付物)。
+ * 单一事实源:mock lead 确定性生成 / omp lead 按 prompt 模板自写 / 平台在
+ * taskEngine.complete 保底合成 —— 三路径同构,目标/判定标准/完成过程/最终成果/结论。
+ */
+export function synthesizeGoalSummary(
+  task: WorkspaceTask,
+  children: WorkspaceTask[],
+  criteria: string,
+): A2AArtifact {
+  const results = children
+    .flatMap(c => c.artifacts.flatMap(a => (a.name === 'input' ? [] : a.parts)))
+    .filter((p): p is { text: string } => 'text' in p)
+    .map(p => p.text.trim())
+    .filter(t => t.length > 0)
+    .slice(-8)
+  const conclusion = [
+    `【目标完成总结】`,
+    `目标: ${task.title}`,
+    `判定标准: ${criteria}`,
+    `完成过程: ${children.length > 0 ? children.map(c => `「${c.title}」`).join(' → ') : '(单任务达成)'} 全部完成`,
+    `最终成果: ${results.length > 0 ? results.join('; ') : '(交付物见任务 artifacts)'}`,
+    `结论: 目标已达成,全部任务完成。`,
+  ].join('\n')
+  return {
+    artifactId: randomUUID(),
+    name: 'goal-summary',
+    parts: [
+      { text: conclusion },
+      { text: `标准:${criteria}` },
+      { text: `子任务:${children.length > 0 ? children.map(c => c.title).join(' + ') : task.title}` },
+    ],
+  }
+}

package/server/services/workshop/runtime/mailbox.ts

@@ -0,0 +1,148 @@
+/**
+ * Mailbox — 持久化 FIFO 队列(messages 表)。
+ * 每个 Agent 一个实例;enqueue 落库 pending + 唤醒;dequeue 用 promise 门闩挂起等待。
+ * at-least-once:dequeue 置 consuming;服务重启时上层调用 resetConsuming 重投。
+ * 权威契约见 docs/superpowers/plans/2026-08-13-agent-workshop-multi-agent.md 核心契约块 T3。
+ */
+import type { A2AMessage, Part } from '../types/a2a'
+import { parseJson } from '../db/database'
+import type { MessageRow } from '../db/database'
+import type { MessageRepo } from '../db/message.repo'
+
+/** promise 门闩:resolve 后重建,供 dequeue 反复挂起 */
+interface Gate {
+  promise: Promise<void>
+  resolve: () => void
+}
+
+function newGate(): Gate {
+  let resolve!: () => void
+  const promise = new Promise<void>((r) => {
+    resolve = r
+  })
+  return { promise, resolve }
+}
+
+/** MessageRow → A2AMessage(parts/metadata 反序列化) */
+export function rowToMessage(row: MessageRow): A2AMessage {
+  return {
+    messageId: row.id,
+    contextId: row.channelId,
+    taskId: row.taskId ?? undefined,
+    role: row.role as 'ROLE_USER' | 'ROLE_AGENT',
+    parts: parseJson<Part[]>(row.partsJson, []),
+    metadata: parseJson<Record<string, unknown>>(row.metadataJson, {}),
+  }
+}
+
+export class Mailbox {
+  readonly agentId: string
+  readonly channelId: string
+  private gate: Gate = newGate()
+  private closed = false
+  /** 外部通知回调(如唤醒调度循环);由 AgentRuntime/Manager 注入 */
+  private onWake: () => void
+  /** 到信回调注册(poll_messages 长轮询即时唤醒;注册方自带注销句柄) */
+  private arrivalCbs = new Set<() => void>()
+
+  constructor(
+    private messageRepo: MessageRepo,
+    channelId: string,
+    agentId: string,
+    wake: () => void,
+  ) {
+    this.channelId = channelId
+    this.agentId = agentId
+    this.onWake = wake
+  }
+
+  /** 投递:落库 pending + 唤醒 dequeue 门闩 + 到信回调 + 通知外部 */
+  enqueue(message: A2AMessage): void {
+    if (this.closed) return
+    this.messageRepo.create({
+      // 保留发送方 messageId 作为落库 id:API 返回的 messageId 才能与历史/状态一致关联
+      id: message.messageId,
+      channelId: message.contextId,
+      taskId: message.taskId ?? null,
+      fromAgentId: (message.metadata?.['x-aw-from-agent'] as string | undefined) ?? null,
+      toAgentId: this.agentId,
+      role: message.role,
+      parts: message.parts,
+      metadata: message.metadata,
+    })
+    this.wake()
+    for (const cb of this.arrivalCbs) {
+      try {
+        cb()
+      }
+      catch { /* 回调异常不阻断投递 */ }
+    }
+    this.onWake()
+  }
+
+  /** 到信回调注册(即时唤醒阻塞等待方);返回注销函数 */
+  onArrival(cb: () => void): () => void {
+    this.arrivalCbs.add(cb)
+    return () => {
+      this.arrivalCbs.delete(cb)
+    }
+  }
+
+  /** 取出下一条(FIFO);无消息时挂起等待;关闭后返回 null */
+  async dequeue(): Promise<A2AMessage | null> {
+    for (;;) {
+      if (this.closed) return null
+      // 先取门闩引用再查询:查询空档内 enqueue 的 releaseGate 才不会丢唤醒
+      // (若查询后才取引用,新门闩替换旧门闩 → 挂在未触发的门闩上永久沉睡)
+      const gate = this.gate
+      const row = this.messageRepo.firstPendingByChannelAgent(this.channelId, this.agentId)
+      if (row) {
+        // 原子认领:认领失败 = 消息已被 steer 注入或 poll_messages 读即取
+        // (唯一所有权),让路重查下一条——消费循环绝不重复处理他人消息
+        if (!this.messageRepo.claim(row.id)) continue
+        return rowToMessage(row)
+      }
+      // 门闩挂起 + 15s 兜底重查:任何唤醒丢失路径自愈(消息最多滞后 15s)
+      await Promise.race([
+        gate.promise,
+        new Promise<void>(resolve => setTimeout(resolve, 15_000)),
+      ])
+    }
+  }
+
+  /** 原子认领(pending → consuming):多方竞争下唯一所有权;认领失败返回 false */
+  claim(messageId: string): boolean {
+    return this.messageRepo.claim(messageId)
+  }
+
+  /** 只读查看未消费消息(不改变状态) */
+  async peek(limit: number): Promise<A2AMessage[]> {
+    return this.messageRepo.listPendingByChannelAgent(this.channelId, this.agentId, limit).map(rowToMessage)
+  }
+
+  /** 标记已消费 */
+  markConsumed(messageId: string): void {
+    this.messageRepo.markConsumed(messageId)
+  }
+
+  /** 回合失败重投(consuming → pending);返回是否实际重投 */
+  requeue(messageId: string): boolean {
+    return this.messageRepo.requeue(messageId)
+  }
+
+  /** 外部唤醒:解除 dequeue 挂起(供 manager 在 taskEngine 直接落库后唤醒) */
+  wake(): void {
+    this.releaseGate()
+  }
+
+  /** 关闭邮箱:解除 dequeue 挂起,后续 dequeue 返回 null(供 AgentRuntime.stop) */
+  close(): void {
+    this.closed = true
+    this.releaseGate()
+  }
+
+  private releaseGate(): void {
+    this.gate.resolve()
+    this.gate = newGate()
+  }
+}