agentworkshop 0.7.41 → 0.7.46

package/server/api/workshop/ws/hub.ts

@@ -0,0 +1,133 @@
+/**
+ * hub↔manager 绑定自愈 / 查询参数 / 场景 peer / 控制帧与流帧发送
+ * (由 server/api/workshop/ws.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { AgentChannelManager, ManagerDeps } from '../../../services/workshop/runtime/manager'
+import type { AgentRuntime, TaskEngine } from '../../../services/workshop/runtime/agent-runtime'
+import type { ChannelStream, WsPeer } from './shared'
+import { PEER_SEND_BUDGET_BYTES, hub, streams } from './shared'
+import { ensureStream } from './streams'
+import { flushDbBuffer } from './db-buffer'
+import { getWorkshopManager } from '../../../plugins/workshop'
+import { registerScenePeer, setPeerVisibleLines } from '../../../services/workshop/scene-events'
+import { visibleLineIds } from '../../../services/workshop/permissions'
+
+export function ensureHubBound(manager: AgentChannelManager): void {
+  if (hub.boundManager === manager) return
+  hub.boundManager = manager
+  for (const stream of [...streams.values()]) {
+    const channelId = stream.channelId
+    // manager 更替前刷净落库缓冲:流即将重建,缓冲帧必须先落库保序
+    try {
+      flushDbBuffer(manager, stream)
+    }
+    catch { /* 尽力刷盘 */ }
+    // seq/ring 延续:客户端游标(已收到的 lastSeq)不变,重建流必须接续原 seq 递增,
+    // 否则新事件 seq 从 1 重来会被客户端 ingest 的 seq>lastSeq 判重逻辑整段丢弃。
+    const seq = stream.seq
+    const ring = stream.ring
+    const peers = [...stream.peers]
+    for (const unsub of stream.unsubs) {
+      try {
+        unsub()
+      }
+      catch { /* 尽力清理 */ }
+    }
+    streams.delete(channelId)
+    // 有 peer 的 channel 立即按新 manager 重建(peers 平移 + seq/ring 延续);无 peer 的任其自然重建
+    if (peers.length > 0) {
+      const fresh = ensureStream(manager, channelId)
+      if (fresh) {
+        fresh.peers = new Set(peers)
+        fresh.seq = seq
+        fresh.ring = ring
+      }
+    }
+  }
+}
+
+// 模块加载自愈(HMR):nitro reload 后新模块消息入口触达不了旧 socket(旧 handler 继续应答),
+// 加载时主动把 hub 换绑到当前 manager(peers 平移,存活连接即刻恢复推送)。
+// manager 可能尚未重新 init(plugin 时序)→ 有限重试等待就绪。
+if (hub.streams.size > 0) {
+  const rebindWhenReady = (attempt: number): void => {
+    try {
+      ensureHubBound(getWorkshopManager())
+    }
+    catch {
+      if (attempt < 50) setTimeout(() => rebindWhenReady(attempt + 1), 200) // ≤10s
+    }
+  }
+  setTimeout(() => rebindWhenReady(0), 50)
+}
+
+/** manager 内部结构(类型收窄:公开 API 未暴露 repos/运行时映射) */
+export interface ManagerInternals {
+  deps: ManagerDeps
+  agentIndex: Map<string, AgentRuntime>
+  /** channel → 事件总线(生命期与管理器同源;空闲卸载后 channel 重激活会重建) */
+  buses: Map<string, object>
+  getTaskEngine(): TaskEngine
+}
+
+export function internalsOf(manager: AgentChannelManager): ManagerInternals {
+  return manager as unknown as ManagerInternals
+}
+
+export function resolveQueryParam(peer: WsPeer, name: string): string | undefined {
+  const req = (peer as unknown as { request?: Request }).request
+  if (!req) return undefined
+  return new URL(req.url).searchParams.get(name) ?? undefined
+}
+
+export function resolveChannelIdFromUrl(peer: WsPeer): string | undefined {
+  return resolveQueryParam(peer, 'channelId') ?? resolveQueryParam(peer, 'channel_id')
+}
+
+/** 场景事件注册(鉴权后):按用户产线可见集挂 per-peer 过滤,未经鉴权的 peer 不注册 */
+export function attachScenePeer(peer: WsPeer, user: { id: string, role: string }): void {
+  setPeerVisibleLines(peer, visibleLineIds(user))
+  registerScenePeer(peer)
+}
+
+/** 安全发送控制帧(error/pong/snapshot;死连接静默丢弃) */
+export function sendControl(peer: WsPeer, obj: unknown): void {
+  try {
+    peer.send(JSON.stringify(obj))
+  }
+  catch { /* 死连接 */ }
+}
+
+/** 每 peer 发送预算窗(慢消费者守卫;正常 peer 零延迟影响) */
+export const peerBudget = new WeakMap<WsPeer, { bytes: number, winStart: number }>()
+
+export function sendFrame(stream: ChannelStream, peer: WsPeer, frame: string): void {
+  // 预算:同一秒窗内累计发送超限 → 判定慢消费者,断开交由客户端重连快照对齐
+  const now = Date.now()
+  let b = peerBudget.get(peer)
+  if (!b || now - b.winStart >= 1000) {
+    b = { bytes: 0, winStart: now }
+    peerBudget.set(peer, b)
+  }
+  b.bytes += frame.length
+  if (b.bytes > PEER_SEND_BUDGET_BYTES) {
+    try {
+      peer.close(1013, 'slow consumer')
+    }
+    catch { /* already gone */ }
+    stream.peers.delete(peer)
+    return
+  }
+  try {
+    peer.send(frame)
+  }
+  catch {
+    // 死连接(TCP 硬断未走 close 回调):移除防后续广播中断
+    stream.peers.delete(peer)
+  }
+}
+
+/** 落库缓冲刷盘窗口(ms):全部帧型按此节奏批量事务落库 */
+export const DB_FLUSH_MS = 400
+
+/** 刷盘缓冲中的事件(单事务批量 insert;清定时器) */

package/server/api/workshop/ws/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Workshop WebSocket Hub(AEP v1)—— 前端观察入口的事件直推实现
+ *
+ * 由原单文件按职责拆分而来;此处保持**原文件的公开 API 与 import 路径不变**
+ * (目录 index 解析),外部调用方无需改动。
+ *
+ * 模块划分:
+ *   shared.ts              协议头注释 / 常量 / WsPeer 与 ChannelStream 类型 / hub 单例
+ *   hub.ts                 hub↔manager 绑定自愈 / 查询参数 / 场景 peer / 控制帧与流帧发送
+ *   db-buffer.ts           落库聚合缓冲刷盘(400ms 批量事务)
+ *   publish.ts             事件发布(seq/环形缓冲/慢消费者断开)与快照构建
+ *   event-mapping.ts       AgentEvent → AEP 帧映射
+ *   subscriptions.ts       频道总线订阅绑定 / HITL 待办订阅
+ *   audience.ts            HITL 受众与管理员集合解析
+ *   streams.ts             流生命周期:陈旧重订 / 回收 / 确保存在
+ *   peer-sub.ts            peer 订阅/退订与聊天快照投影
+ *   handlers.ts            场景布局广播 / 事件记录器预热 / defineWebSocketHandler 入口
+ *   notification-uplink.ts 用户级通知上行(subNotifications / unsub / read)
+ */
+export { ensureStream } from './streams'
+export { publishSceneLayoutEvent, ensureAllEventRecorders } from './handlers'
+export { broadcastSceneEvent } from './peer-sub'
+export { default } from './handlers'

package/server/api/workshop/ws/notification-uplink.ts

@@ -0,0 +1,77 @@
+/**
+ * 用户级通知上行(subNotifications / unsub / read)
+ * (由 server/api/workshop/ws.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { AepNotification } from '../../../../shared/workshop-protocol'
+import type { AgentChannelManager } from '../../../services/workshop/runtime/manager'
+import type { WsPeer } from './shared'
+import { AEP_VERSION } from './shared'
+import { projectNotification } from '../../../services/workshop/runtime/chat-projection'
+import { sendControl } from './hub'
+import { unbindUserPeer, userIdOfPeer } from '../../../services/workshop/runtime/user-notification-hub'
+
+/**
+ * 用户级通知上行处理(subNotifications / unsubNotifications / notification.read)。
+ *
+ * 隔离前提:peer 的 userId **只**来自连接期 token 解析(subscribePeer 或 open 时绑定);
+ * 上行帧里即使带 userId 也一律忽略 —— 客户端不能订阅或标记他人的通知。
+ */
+export function handleNotificationUplink(
+  manager: AgentChannelManager,
+  peer: WsPeer,
+  parsed: { type?: unknown, cursor?: unknown, id?: unknown, channelId?: unknown, all?: unknown },
+): void {
+  const userId = userIdOfPeer(peer)
+  if (!userId) {
+    sendControl(peer, { v: AEP_VERSION, type: 'error', seq: 0, at: new Date().toISOString(), channelId: '', payload: { code: 'USER_UNAUTHORIZED', message: '通知订阅需要已认证的用户 token(连接 ?token= 或 sub 帧 token)' } })
+    return
+  }
+  const notifications = manager.groupChat.notifications
+  if (parsed.type === 'unsubNotifications') {
+    sendControl(peer, { v: AEP_VERSION, type: 'notification.unsubscribed', seq: 0, at: new Date().toISOString(), channelId: '', payload: { ok: true } })
+    return
+  }
+  if (parsed.type === 'notification.read') {
+    const result = manager.markNotificationsRead(userId, {
+      id: typeof parsed.id === 'string' ? parsed.id : undefined,
+      channelId: typeof parsed.channelId === 'string' ? parsed.channelId : undefined,
+      all: parsed.all === true,
+    })
+    sendControl(peer, { v: AEP_VERSION, type: 'notification.read.ack', seq: 0, at: new Date().toISOString(), channelId: '', payload: { ...result, unreadCount: notifications.unreadCount(userId) } })
+    return
+  }
+  // subNotifications:按游标补发(通知表是事实源;重连后不丢不重)
+  const rawCursor = parsed.cursor as { createdAt?: unknown, id?: unknown } | null | undefined
+  let cursor: { createdAt: string, id: string } | null = null
+  if (rawCursor && typeof rawCursor.createdAt === 'string' && typeof rawCursor.id === 'string') {
+    cursor = { createdAt: rawCursor.createdAt, id: rawCursor.id }
+  }
+  const rows = manager.listNotificationsAfter(userId, cursor, 200)
+  for (const r of rows) {
+    // 与 REST 快照 / 定向推送共用同一投影:三处此前各写一份字段映射,
+    // 任一漏改都会让同一条通知在不同通道里形状不同(前端按 eventId 去重,形状漂移会渲染成两种样子)。
+    const payload: AepNotification = projectNotification(r)
+    // 补发经 peer 直发(带 eventId 幂等键;客户端按 eventId 去重)
+    try {
+      peer.send(JSON.stringify({ v: AEP_VERSION, type: 'notification.created', seq: 0, at: new Date().toISOString(), channelId: r.channelId ?? '', payload }))
+    }
+    catch {
+      unbindUserPeer(peer)
+      return
+    }
+  }
+  sendControl(peer, {
+    v: AEP_VERSION,
+    type: 'notification.snapshot',
+    seq: 0,
+    at: new Date().toISOString(),
+    channelId: '',
+    payload: {
+      replayed: rows.length,
+      unreadCount: notifications.unreadCount(userId),
+      nextCursor: rows.length > 0
+        ? { createdAt: rows[rows.length - 1]!.createdAt, id: rows[rows.length - 1]!.id }
+        : cursor,
+    },
+  })
+}

package/server/api/workshop/ws/peer-sub.ts

@@ -0,0 +1,128 @@
+/**
+ * peer 订阅/退订与聊天快照投影
+ * (由 server/api/workshop/ws.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { AgentChannelManager } from '../../../services/workshop/runtime/manager'
+import type { WsPeer } from './shared'
+import { AEP_VERSION, peerChannels, streams } from './shared'
+import { attachScenePeer, sendControl, sendFrame } from './hub'
+import { bindUserPeer } from '../../../services/workshop/runtime/user-notification-hub'
+import { buildSnapshot } from './publish'
+import { ensureStream } from './streams'
+import { resolveUserByToken } from '../../../services/user.service'
+// 非管理者快照白名单投影(拆段时生成器漏了这一条:标识符只出现在三元表达式的对象展开里)
+import { projectManagementSnapshotForMember } from '../../../services/workshop/runtime/chat-projection'
+
+export function subscribePeer(manager: AgentChannelManager, peer: WsPeer, channelId: string, lastSeq?: number, userToken?: string): void { // v17:群成员鉴权(requireChannelMember);管理面字段按 canManage 投影(§13.1)
+  if (!userToken) {
+    sendControl(peer, { v: AEP_VERSION, type: 'error', seq: 0, at: new Date().toISOString(), channelId, payload: { code: 'USER_UNAUTHORIZED', message: 'WS 订阅需要用户 token(sub 帧携带 token 字段或连接 ?token= 查询参数)' } })
+    return
+  }
+  const user = resolveUserByToken(userToken)
+  if (!user) {
+    sendControl(peer, { v: AEP_VERSION, type: 'error', seq: 0, at: new Date().toISOString(), channelId, payload: { code: 'USER_UNAUTHORIZED', message: '用户 token 无效' } })
+    return
+  }
+  // v17:token 认证成功后绑定 peer→userId(用户级通知 hub 的 recipient 隔离基础)
+  bindUserPeer(peer, user.id)
+  let canManage: boolean
+  try {
+    // 成员守卫:owner 或 active 群成员可订阅(群聊读取/发言/WS/HITL 可见性同口径);
+    // 管理能力另行判定,仅用于快照投影深度。
+    manager.requireChannelMember(channelId, user)
+    canManage = manager.channelPermissionsOf(channelId, user).canManage
+  }
+  catch (err) {
+    const e = err as { code?: string, message?: string }
+    sendControl(peer, { v: AEP_VERSION, type: 'error', seq: 0, at: new Date().toISOString(), channelId, payload: { code: e.code ?? 'FORBIDDEN', message: e.message ?? 'channel 不可见' } })
+    return
+  }
+  const stream = ensureStream(manager, channelId)
+  if (!stream) {
+    sendControl(peer, { v: AEP_VERSION, type: 'error', seq: 0, at: new Date().toISOString(), channelId, payload: { code: 'NOT_FOUND', message: `channel 不存在: ${channelId}` } })
+    return
+  }
+  stream.peers.add(peer)
+  // 共享场景事件注册表:daq 等无频道归属广播由此直达该 peer(sub 鉴权成功后补挂)
+  attachScenePeer(peer, user)
+  let channels = peerChannels.get(peer)
+  if (!channels) {
+    channels = new Set()
+    peerChannels.set(peer, channels)
+  }
+  channels.add(channelId)
+  // 对齐策略:无游标(lastSeq 缺省/为 0)/ seq 倒退(服务重启)/ 缓冲窗外 →
+  // channel.snapshot 全量(agents/tasks/queue/messages 基线,客户端事件即实体);
+  // 否则重放缺失段。lastSeq=0 视为"新订阅者"(游标未建立),同样走快照路径——
+  // 仅重放事件会让客户端丢失实体基线(空闲成员/历史任务永远不出现)。
+  const cursor: number | undefined = (lastSeq !== undefined && lastSeq > 0) ? lastSeq : undefined
+  const oldest = stream.ring[0]?.e.seq ?? stream.seq + 1
+  if (cursor === undefined || cursor >= stream.seq || cursor + 1 < oldest) {
+    const snapshot = buildSnapshot(manager, channelId)
+    if (snapshot) {
+      // v17 §13.1:非管理者只拿白名单投影(剔除 config/token/workspace/内部 mailbox/task payload);
+      // 同时附带群聊侧基线(成员/群聊历史/能力/通知游标),成员无需额外 REST 即可渲染群聊。
+      const payload = canManage
+        ? { ...snapshot, chat: safeChatSnapshot(manager, channelId, user), permissions: safePermissions(manager, channelId, user) }
+        : { ...projectManagementSnapshotForMember(snapshot), chat: safeChatSnapshot(manager, channelId, user), permissions: safePermissions(manager, channelId, user) }
+      sendControl(peer, {
+        v: AEP_VERSION,
+        type: 'channel.snapshot',
+        seq: stream.seq,
+        at: new Date().toISOString(),
+        channelId,
+        payload,
+      })
+    }
+  }
+  else {
+    // 已建立游标且缺口在缓冲窗内 → 重放缺失段(快照无需重发)
+    for (const { e } of stream.ring) {
+      if (e.seq > cursor) sendFrame(stream, peer, JSON.stringify(e))
+    }
+  }
+}
+
+/** 群聊快照(容错:群聊层不可用时返回 null,不阻断管理面快照) */
+export function safeChatSnapshot(manager: AgentChannelManager, channelId: string, user: { id: string }): unknown {
+  try {
+    return manager.chatSnapshotOf(channelId, user)
+  }
+  catch {
+    return null
+  }
+}
+
+/** 能力视图(容错同上) */
+export function safePermissions(manager: AgentChannelManager, channelId: string, user: { id: string, role?: string }): unknown {
+  try {
+    return manager.channelPermissionsOf(channelId, user)
+  }
+  catch {
+    return null
+  }
+}
+
+/** 退订 peer(仅移除 peer;流与订阅常驻——全时录制,无订阅者事件仍落库) */
+export function unsubscribePeer(peer: WsPeer, channelId?: string): void {
+  const channels = peerChannels.get(peer)
+  if (!channels) return
+  const targets = channelId ? [channelId] : [...channels]
+  for (const id of targets) {
+    channels.delete(id)
+    streams.get(id)?.peers.delete(peer)
+  }
+  if (channels.size === 0) peerChannels.delete(peer)
+}
+
+/**
+ * 场景事件广播(设备孪生 REST 变更 → 全部已连 peer)。
+ * 设备实例属 workspace 而非 channel,信封 channelId='' 不进 channel 流/不落事件库;
+ * 客户端经 townBus 旁路消费(scene.syncDevices 即时收敛),轮询兜底不变。
+ */
+export { broadcastSceneEvent } from '../../../services/workshop/scene-events'
+
+/**
+ * 频道领地布局事件(scene.layout.saved/removed):经该频道频道流广播(仅订阅该频道的
+ * peer 收到;小镇页订阅全部挂载频道 → 实时同步布局)。走既有 publish 计入 seq/环形缓冲。
+ */

package/server/api/workshop/ws/publish.ts

@@ -0,0 +1,122 @@
+/**
+ * 事件发布(seq/环形缓冲/慢消费者断开)与快照构建
+ * (由 server/api/workshop/ws.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { AepEnvelope, RootQueueView } from '../../../../shared/workshop-protocol'
+import type { AgentChannelManager } from '../../../services/workshop/runtime/manager'
+import type { WorkspaceTask } from '../../../services/workshop/types/task'
+import type { ChannelStream } from './shared'
+import { AEP_VERSION, DB_BUFFER_CAP, RING_BYTES_CAP, RING_CAP, hub } from './shared'
+import { DB_FLUSH_MS, internalsOf, sendFrame } from './hub'
+import { flushDbBuffer } from './db-buffer'
+import { parseJson } from '../../../services/workshop/db/database'
+import { rowToMessage } from '../../../services/workshop/runtime/mailbox'
+
+export function publish(
+  manager: AgentChannelManager,
+  stream: ChannelStream,
+  type: string,
+  payload: unknown,
+  ids: { agentId?: string, taskId?: string } = {},
+): AepEnvelope {
+  stream.seq += 1
+  const e: AepEnvelope = {
+    v: AEP_VERSION,
+    type,
+    seq: stream.seq,
+    at: new Date().toISOString(),
+    channelId: stream.channelId,
+    ...ids,
+    payload: payload as AepEnvelope['payload'],
+  }
+  // 环形缓冲:条数 + 字节双封顶(帧串行化一次,字节数直接可得)
+  const frame = JSON.stringify(e)
+  stream.ring.push({ e, bytes: frame.length })
+  stream.ringBytes += frame.length
+  while ((stream.ringBytes > RING_BYTES_CAP || stream.ring.length > RING_CAP) && stream.ring.length > 1) {
+    const evicted = stream.ring.shift()!
+    stream.ringBytes -= evicted.bytes
+  }
+  // 持久化(server 驱动):全部帧型进有序聚合缓冲,400ms 单事务批量刷盘。
+  // 缓冲滞留超限即刷(库故障时防无限涨);失败仅记日志,不影响实时推送。
+  stream.dbBuffer.push(e)
+  if (stream.dbBuffer.length >= DB_BUFFER_CAP) {
+    flushDbBuffer(manager, stream)
+  }
+  else if (!stream.dbFlushTimer) {
+    stream.dbFlushTimer = setTimeout(() => {
+      stream.dbFlushTimer = null
+      if (hub.boundManager) flushDbBuffer(hub.boundManager, stream)
+    }, DB_FLUSH_MS)
+    stream.dbFlushTimer.unref?.()
+  }
+  for (const peer of stream.peers) sendFrame(stream, peer, frame)
+  return e
+}
+
+/** 采集 channel 快照(agents 含队列上下文;queue 总览) */
+export function buildSnapshot(manager: AgentChannelManager, channelId: string): Record<string, unknown> | null {
+  const internal = internalsOf(manager)
+  const channel = internal.deps.repos.channels.findById(channelId)
+  if (!channel) return null
+  const memberRows = internal.deps.repos.channelAgents.listByChannel(channelId)
+  const agents = memberRows.map((m) => {
+    const rt = internal.agentIndex.get(`${channelId}\u0000${m.id}`)
+    const view = rt ? rt.getQueueView() : internal.getTaskEngine().queueViewOf(channelId, m.id)
+    return {
+      agentId: m.id,
+      name: m.name,
+      role: m.role,
+      harness: m.harness,
+      enabled: m.enabled,
+      config: parseJson<Record<string, unknown>>(m.configJson, {}),
+      state: rt ? rt.getState() : 'idle',
+      currentTaskId: view.current?.id ?? null,
+      currentTaskTitle: view.current?.title ?? null,
+      currentTaskProgress: view.current?.progress != null ? view.current.progress : null,
+      queued: view.queued.length,
+      completed: view.completed.length,
+      supervision: rt?.getSupervisionStatus?.(),
+      continuity: rt?.getContinuity?.(),
+    }
+  })
+  const tasks = internal.getTaskEngine().list(channelId)
+  const rootQueue = rootQueueViewOf(internal.getTaskEngine().rootQueue(channelId))
+  const recentMessages = internal.deps.repos.messages.listRecentByChannel(channelId, 50).map(rowToMessage)
+  // queue 总览 = agents 的队列上下文规范化(与 queueOverview 同口径,免异步)
+  const queue = agents.map(a => ({
+    agentId: a.agentId,
+    name: a.name,
+    role: a.role,
+    state: a.state,
+    currentTaskId: a.currentTaskId ?? null,
+    currentTaskTitle: a.currentTaskTitle ?? null,
+    currentTaskProgress: a.currentTaskProgress ?? null,
+    queuedCount: a.queued ?? 0,
+    completedCount: a.completed ?? 0,
+  }))
+  return { channelId, channel, agents, tasks, rootQueue, queue, messages: recentMessages }
+}
+
+/**
+ * 根任务队列 → 只读 AEP 投影(§2.2/§3.4)。
+ * 排队位次由后端派生(position 从 2 起):前端不再自行推导 active root,
+ * 避免前后端对「谁在跑」给出相反结论。
+ */
+export function rootQueueViewOf(queue: { activeRoot: WorkspaceTask | null, queuedRoots: WorkspaceTask[], completedRoots: WorkspaceTask[] }): RootQueueView {
+  return {
+    activeRootId: queue.activeRoot?.id ?? null,
+    queuedRoots: queue.queuedRoots.map((t, i) => ({
+      taskId: t.id,
+      title: t.title,
+      position: i + 2,
+      state: t.state,
+      createdAt: t.createdAt,
+    })),
+    completedRoots: queue.completedRoots.length,
+    activeRootCount: queue.activeRoot ? 1 : 0,
+    queuedRootCount: queue.queuedRoots.length,
+  }
+}
+
+/** AgentEvent 五变体 → AEP 事件 */

package/server/api/workshop/ws/shared.ts

@@ -0,0 +1,94 @@
+/**
+ * 协议头注释 / 常量 / WsPeer 与 ChannelStream 类型 / hub 单例
+ * (由 server/api/workshop/ws.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type { AepEnvelope } from '../../../../shared/workshop-protocol'
+import type { AgentChannelManager } from '../../../services/workshop/runtime/manager'
+import { createLogger } from '../../../services/workshop/logger'
+import { retentionSettings } from '../../../services/workshop/settings'
+
+/**
+ * WebSocket Hub(AEP v1)— 前端观察入口,事件驱动直推。
+ * 路径 /api/workshop/ws?channelId=xxx(缺省 channelId 可连后上行 sub 订阅多 channel)。
+ *
+ * 协议:Agent Event Protocol(权威定义 #shared/workshop-protocol)
+ *  - 下行信封:{ v, type, seq, at, channelId, agentId?, taskId?, payload }
+ *    type/payload 与旧 hub 帧兼容(agent.status/task.status/task.progress/
+ *    a2a.artifact/a2a.message/channel.snapshot/error/pong),信封字段为增量。
+ *  - 上行:{type:'ping'} → pong;{type:'sub',channelId,lastSeq?} 断线续传重放;
+ *    {type:'unsub',channelId} 退订。
+ *
+ * 推送机制:直订 manager ChannelBus(subscribeChannelEvents/onTaskEvent/
+ * onAgentStatus/subscribeChannelMessages/subscribeMemoryEvents)——无轮询;
+ * per-channel 单调 seq + 环形缓冲(5000),sub 带 lastSeq 时重放缺失段,
+ * 缓冲窗外/seq 倒退(服务重启)→ 下发 channel.snapshot 全量对齐。
+ */
+
+export const log = createLogger('workshop.ws')
+
+export const AEP_VERSION = 1
+export const RING_CAP = 5000
+/** ring 字节上限(含大 artifact 载荷的长会话内存有界;超出丢最旧) */
+export const RING_BYTES_CAP = 4 * 1024 * 1024
+/** 落库聚合缓冲上限(滞留超限即刷,防库故障时缓冲无限涨) */
+export const DB_BUFFER_CAP = 2000
+/** 事件保留期(天;retention.events_days,env AW_EVENTS_RETENTION_D 可覆盖) */
+export const EVENTS_RETENTION_DAYS = (): number => retentionSettings().events_days
+/** 单 peer 发送预算(字节/秒):超限视为慢消费者断开(1013),客户端重连快照对齐。
+ *  实测常态 ~85 帧/秒 ≈ 0.1MB/s,8MB/s 保留 ~80× 余量,同时封住病态积压
+ *  (原 32MB/s 过宽:慢客户端断开前每秒可积压 32MB 序列化帧) */
+export const PEER_SEND_BUDGET_BYTES = 8 * 1024 * 1024
+
+/** 最小 peer 接口(h3 2.x 未 re-export crossws 类型,duck typing;与 game/ws.ts 同风格) */
+export interface WsPeer {
+  send(data: string | Uint8Array): void
+  close(code?: number, reason?: string): void
+}
+
+/** channel 级事件流:seq 单调递增 + 环形缓冲 + 订阅清理 + 优雅保留窗口 */
+export interface ChannelStream {
+  channelId: string
+  seq: number
+  /** 环形缓冲(条数 RING_CAP + 字节 RING_BYTES_CAP 双封顶;重放/续传窗口) */
+  ring: Array<{ e: AepEnvelope, bytes: number }>
+  ringBytes: number
+  peers: Set<WsPeer>
+  unsubs: Array<() => void>
+  /**
+   * HITL 待办事件订阅(hitl-registry 模块级总线 → 频道流)。
+   * 单独存放、不进 unsubs:rebindStreamIfStale 会整体清空 unsubs 重订总线,
+   * 而 registry 订阅与总线生命周期无关,只在建流/回收时挂接一次。
+   */
+  hitlUnsub: (() => void) | null
+  /** 当前已订阅的 channel 总线对象(总线生命期短于 stream:空闲卸载会重建 bus → 需重订) */
+  busRef: object | null
+  /**
+   * 落库聚合缓冲(全部事件类型,保持发布序):逐帧同步 insert 会阻塞事件循环;
+   * 400ms 批量事务刷盘(单次 fsync 落整批)。实时广播不经缓冲(逐帧直推),
+   * 只有持久化走聚合路径 —— 与旧 delta-only 缓冲同语义,推广到全部帧型。
+   */
+  dbBuffer: AepEnvelope[]
+  dbFlushTimer: NodeJS.Timeout | null
+}
+
+/**
+ * HMR 存活:nitro dev 热重载重建模块图(模块级 Map 随之蒸发),但 crossws peer 连接仍存活——
+ * hub 状态挂 globalThis 跨模块实例存活;manager 更替(plugin 重新 init)时由 ensureHubBound
+ * 自愈式重建订阅(peers 平移),存活连接在下一帧(最长一个 ping 周期)自动恢复事件流。
+ */
+export interface HubState {
+  streams: Map<string, ChannelStream>
+  peerChannels: Map<WsPeer, Set<string>>
+  boundManager: AgentChannelManager | null
+}
+export const hubGlobal = globalThis as typeof globalThis & { __workshopWsHub?: HubState }
+export const hub: HubState = hubGlobal.__workshopWsHub
+  ?? (hubGlobal.__workshopWsHub = { streams: new Map(), peerChannels: new Map(), boundManager: null })
+export const streams = hub.streams
+export const peerChannels = hub.peerChannels
+
+/**
+ * hub ↔ manager 绑定校验(消息入口调用):manager 更替(HMR 后 plugin 重新 init)时,
+ * 退订旧 manager 总线上的全部 stream 并按新 manager 重建订阅;已注册 peers 平移,
+ * ring/seq 延续,客户端无需重连即恢复事件流。
+ */