agentworkshop 0.2.1

package/server/services/workshop/agents/agent-interface.ts

@@ -0,0 +1,219 @@
+/**
+ * Agent 接口层 — harness 无关统一契约。
+ * 定义 Agent 元信息、运行请求/上下文、事件流、调度快照与决策、以及所有 harness impl 必须实现的 AgentInterface。
+ * 仅类型定义,无运行时逻辑;供运行时层(runtime)、调度层(scheduler)与 impl 层共同消费。
+ * 权威契约见 docs/superpowers/plans/2026-08-13-agent-workshop-multi-agent.md 核心契约块。
+ */
+import type { A2AMessage, A2AArtifact, A2AError, ChannelMail, Part } from '../types/a2a'
+import type { WorkspaceTask, AgentTaskQueueView, AgentStatusView } from '../types/task'
+
+/** Agent 元信息:Channel 内成员声明(hook harness 类型与配置) */
+export interface AgentInfo {
+  id: string
+  channelId: string
+  name: string
+  harness: string
+  role: 'lead' | 'worker'
+  config: Record<string, unknown>
+  token?: string
+  /** 实例启停(1 启用 / 0 禁用;模板视图无此字段) */
+  enabled?: number
+}
+
+/** 运行请求:平台向 Agent 投递的一次消息输入 */
+export interface AgentRunRequest {
+  /** A2A 消息;任务类消息携带 taskId + metadata['x-aw-task-kind'] */
+  message: A2AMessage
+  taskId?: string
+  /** = channelId */
+  contextId: string
+  fromAgentId: string | null
+  toAgentId: string | null
+  /** 平台记忆系统装配的历史上下文块(可选;harness 自主决定是否注入 prompt) */
+  memory?: string
+}
+
+/** Agent 自主作业能力面(MCP 工具子集,进程内直调) */
+export interface AgentWorkspace {
+  /** 列出本 Channel 同事 */
+  listAgents(): Promise<AgentInfo[]>
+  /** 任务分发(仅 lead;创建子任务并指派) */
+  dispatchTask(input: { parentTaskId?: string, assigneeId: string, title: string, description?: string, parts?: Part[], routeReason?: string }): Promise<WorkspaceTask>
+  /** 查看同 Channel 任务列表(含同事) */
+  listTasks(): Promise<WorkspaceTask[]>
+  /** 查看指定任务详情 */
+  getTask(taskId: string): Promise<WorkspaceTask>
+  /** 上报进度/成果 */
+  reportTask(input: { taskId: string, progress?: number, artifact?: A2AArtifact, message?: string }): Promise<WorkspaceTask>
+  /** 完成任务 */
+  completeTask(taskId: string, artifacts?: A2AArtifact[]): Promise<WorkspaceTask>
+  /** 查看自己的任务队列(待执行 FIFO / 执行中 / 已完成)——每个 agent 自己的任务管理系统 */
+  myQueue(): Promise<AgentTaskQueueView>
+  /** (lead)全员状态 + 队列总览:统一调度与最优调配的观察面 */
+  queueOverview(): Promise<AgentStatusView[]>
+  /** (lead/creator)修改待执行任务(title/description;执行中/终态拒绝) */
+  updateTask(taskId: string, patch: { title?: string, description?: string }): Promise<WorkspaceTask>
+  /** (lead)重新指派任务:待执行(SUBMITTED/ASSIGNED)或 FAILED 可调配到其他 worker */
+  reassignTask(taskId: string, toAgentId: string): Promise<WorkspaceTask>
+  /** 取消任务 */
+  cancelTask(taskId: string): Promise<WorkspaceTask>
+  /** 点对点发消息给同事 */
+  sendMessage(input: { toAgentId: string, parts: Part[], metadata?: Record<string, unknown> }): Promise<A2AMessage>
+  /**
+   * 拒绝指派给自己的任务(能力/范畴不匹配):任务置 FAILED(调度器改派他人),
+   * 并向派发方(任务创建者,缺省 channel lead)回执拒绝原因。
+   */
+  refuseTask(taskId: string, reason: string): Promise<{ task: WorkspaceTask, notifiedTo: string | null }>
+  /** 拉取自己 mailbox 未消费消息 */
+  pollMailbox(limit?: number): Promise<A2AMessage[]>
+  /** 阻塞长轮询未消费消息(到信即时唤醒 + 250ms 兜底;poll_messages 用) */
+  waitMailbox(limit?: number, waitMs?: number): Promise<A2AMessage[]>
+  /** 确认消费自己 mailbox 的协作消息(读即取;任务指派不经此确认,由执行循环处理) */
+  ackMailbox(messageIds: string[]): Promise<void>
+  /** (lead)Channel 邮件全览:全部 agent 间消息(含已消费),按时间倒序;可选按参与方过滤 */
+  listMail(opts?: { limit?: number, agentId?: string }): Promise<ChannelMail[]>
+  /**
+   * 记忆按需抓取(search_memory 工具桥):混合检索(FTS+向量)本人私有域 + Channel 公共域。
+   * scope: auto=私有+公共(默认) / private / shared;返回结构化片段(综合分排序)。
+   */
+  recallMemory(input: { query: string, scope?: 'auto' | 'private' | 'shared', limit?: number }): Promise<Array<{
+    id: string
+    kind: string
+    title: string
+    content: string
+    importance: number
+    createdAt: string
+    score: number
+    source: 'private' | 'shared'
+  }>>
+  /**
+   * 记忆主动沉淀(save_memory 工具桥):Agent 作业中总结的可复用经验/结论。
+   * scope='private' → 本人记忆库;scope='shared' → Channel 公共记忆域(全员可检索)。
+   */
+  saveMemory(input: { title: string, content: string, importance?: number, scope: 'private' | 'shared', dedupKey?: string }): Promise<{ scope: 'private' | 'shared', dedupKey: string }>
+  /** 订阅同事产出 */
+  subscribe(input: { agentIds?: string[] }): Promise<void>
+  /** (lead)在本 channel 内新建团队成员(worker):按需建模板并克隆为独立实例 */
+  createTeamMember(input: {
+    name: string
+    harness?: string
+    config?: Record<string, unknown>
+    templateId?: string
+    reason?: string
+  }): Promise<AgentInfo>
+  /** (lead)更新团队成员(改名/改配置/启停;不能改 lead 自己);变更后运行时重载 */
+  updateTeamMember(agentId: string, patch: {
+    name?: string
+    config?: Record<string, unknown>
+    enabled?: number
+    reason?: string
+  }): Promise<AgentInfo>
+  /** (lead)移除团队成员(worker;不能移除自己);其未终态任务回收集成为 FAILED 待重派 */
+  removeTeamMember(agentId: string, reason?: string): Promise<{ recycledTasks: string[] }>
+}
+
+/** 执行上下文:平台注入的只读能力(Agent 的"手脚") */
+export interface AgentRunContext {
+  agentId: string
+  channelId: string
+  /** Agent 在 Channel 内的角色(lead 可 dispatch) */
+  role: 'lead' | 'worker'
+  workspace: AgentWorkspace
+  signal: AbortSignal
+  /** 平台记忆块(supervise 路径注入;run 路径用 AgentRunRequest.memory) */
+  memory?: string
+}
+
+/** 统一事件流(对齐 A2A StreamResponse):run() 逐条产出的五变体 */
+export type AgentEvent
+  = | { kind: 'status', status: { state: string, message?: A2AMessage, timestamp: string } }
+    | { kind: 'message', message: A2AMessage }
+    | { kind: 'artifact', artifact: A2AArtifact, append?: boolean, lastChunk?: boolean, totalChunks?: number }
+    | { kind: 'error', error: A2AError }
+    | { kind: 'done', final?: { taskId?: string } }
+    /** LLM 流式增量(P2:omp text_delta 透出;AEP agent.delta 事件源;不进 taskEngine) */
+    | { kind: 'delta', delta: { text: string } }
+
+/** 调度快照:SchedulerLoop 每次 tick 喂给 lead 的团队观察 */
+export interface SupervisionSnapshot {
+  tick: number
+  now: number
+  /** 全 channel 任务摘要 */
+  tasks: WorkspaceTask[]
+  /** 成员状态(含队列上下文与实时进度,供 lead 做最优调配与停滞识别) */
+  members: {
+    agentId: string
+    name: string
+    role: 'lead' | 'worker'
+    state: 'idle' | 'busy' | 'stopped'
+    /** 待执行队列长度(快照时刻) */
+    queued?: number
+    /** 执行中任务 id(空闲时 null) */
+    currentTaskId?: string | null
+    /** 执行中任务标题(lead 观察 worker 在干什么,不必翻任务表) */
+    currentTaskTitle?: string | null
+    /** 执行中任务进度 0-100(空闲/未上报为 null;lead 据此判断是否在推进) */
+    currentTaskProgress?: number | null
+    /** 已完成任务数 */
+    completedCount?: number
+    /** 忙碌但进度长期停滞(超 stallMs 未变)→ lead 应介入(notify/reassign/cancel) */
+    stalled?: boolean
+  }[]
+  /** 每个父任务未完成的子任务数 */
+  pendingChildren: Record<string, number>
+  /**
+   * 最近 Channel 邮件(倒序,最新在前;调度循环注入,默认截取最近 20 条)。
+   * 含 worker 间点对点通信/回执——lead 据此判断"结果是否已被某 worker 产出",
+   * 避免把已完成工作重新派发造成浪费。
+   */
+  mail?: ChannelMail[]
+}
+
+/** 调度决策:lead 对快照的回应(空数组 = 本轮无动作) */
+export type SupervisionDecision
+  = | { kind: 'dispatch', parentTaskId?: string, assigneeId: string, title: string, description?: string, parts?: Part[] }
+    | { kind: 'reassign', taskId: string, toAgentId: string }
+    | { kind: 'cancel', taskId: string }
+    | { kind: 'complete', taskId: string, artifacts?: A2AArtifact[] }
+    | { kind: 'notify', toAgentId: string, parts: Part[] }
+    | { kind: 'spawn_agent', name: string, harness?: string, config?: Record<string, unknown>, templateId?: string, reason?: string }
+    | { kind: 'update_agent', agentId: string, name?: string, config?: Record<string, unknown>, enabled?: boolean, reason?: string }
+    | { kind: 'remove_agent', agentId: string, reason?: string }
+/** 执行模式:channel 任务提交时选择 */
+export type ExecutionMode = 'goal' | 'loop' | 'pipeline'
+
+/** 消息优先级:immediate 实时注入(steer);task 任务队列(等当前任务结束消费) */
+export type MessagePriority = 'immediate' | 'task'
+
+/** AgentInterface:所有 harness impl 的唯一契约 */
+export interface AgentInterface {
+  /** 标准流式返回:输入一次,产出统一事件流 */
+  run(request: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent>
+  /** lead 调度决策(可选,仅 role='lead' 时被 SchedulerLoop 调用) */
+  supervise?(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]>
+  /**
+   * 实时消息注入:将文本注入正在运行的 omp 会话。
+   * 返回送达模式:'steer' = 已注入流式会话(同轮可见,可安全标记消费);
+   * 'deferred' = 未能注入(回合被工具阻塞/空闲/发送失败)——消息保持 pending,
+   * 由 poll_messages 即时取走或消费循环起回合处理。
+   */
+  steer?(text: string): Promise<'steer' | 'deferred'>
+  init?(config: { agent: AgentInfo, channelId: string }): Promise<void>
+  dispose?(): Promise<void>
+  /**
+   * 可选:harness 进程资源信息(运行时资源监控用)。
+   * 进程内 harness(mock/claude)无外部进程 → 不实现返回 null。
+   */
+  getProcessInfo?(): { pid: number, alive: boolean, command: string } | null
+  /**
+   * 可选:强制终止 harness 进程(不等优雅退出)。
+   * 终止后调用方(manager)应随之 stop 对应的 AgentRuntime。
+   */
+  killProcess?(): void
+  /**
+   * 可选:harness 进程存活校准(manager sweeper 周期性调用)。
+   * OS 级存活探针:系统休眠/强杀后子进程 exit 事件可能不达父进程,alive 标记失真;
+   * 探到进程已死时收敛为已退出,让在途回合归位、下一回合自动重生子进程。
+   */
+  reconcileProcess?(): void
+}

package/server/services/workshop/agents/claude-agent.ts

@@ -0,0 +1,47 @@
+/**
+ * ClaudeSdkAgentImpl — claude harness 适配骨架(T8)。
+ * run():读取 config(apiKey/model 等);缺失 apiKey 时以 {kind:'error'} 首事件优雅失败
+ * (HARNESS_NOT_CONFIGURED),平台随即结束事件流并把消息置 consumed 不重试(§9 错误处理)。
+ * 已配置时 TODO 标记真实 Claude Agent SDK 流 → AgentEvent 的映射接入点
+ * (本期不实现真实 SDK 调用)。
+ * supervise 未实现:lead 调度决策由平台内置规则引擎兜底(§5.6)。
+ * 权威契约见 docs/superpowers/specs/2026-08-13-agent-workshop-multi-agent-design.md §4/§9。
+ */
+import type {
+  AgentEvent,
+  AgentInterface,
+  AgentRunContext,
+  AgentRunRequest,
+} from './agent-interface'
+
+export class ClaudeSdkAgentImpl implements AgentInterface {
+  private readonly apiKey: string | undefined
+  private readonly model: string | undefined
+
+  constructor(config: Record<string, unknown> = {}) {
+    this.apiKey = typeof config.apiKey === 'string' ? config.apiKey : undefined
+    this.model = typeof config.model === 'string' ? config.model : undefined
+  }
+
+  async* run(request: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent> {
+    if (!this.apiKey) {
+      yield {
+        kind: 'error',
+        error: { code: 'HARNESS_NOT_CONFIGURED', message: 'Claude harness 未配置(缺 apiKey)' },
+      }
+      return
+    }
+    // TODO(接入点):config 齐备时,在此将 Claude Agent SDK 的流式输出映射为统一 AgentEvent——
+    //   1. SDK 会话初始化:apiKey/model 取自 config,contextId=request.contextId 关联 channel
+    //   2. 任务消息(request.message.parts + metadata['x-aw-task-kind']/['x-aw-task-id'])
+    //      组装为首轮用户输入;SDK tool_use 工具映射到 ctx.workspace 的进程内直调能力面
+    //      (dispatchTask/reportTask/completeTask/sendMessage 等,见 §4.1 AgentWorkspace)
+    //   3. 事件映射:SDK 文本增量 → {kind:'status', status:{state,message,timestamp}};
+    //      工具执行产出 → {kind:'artifact'}(分块用 append+totalChunks,平台按块数折算进度);
+    //      会话结束 → {kind:'done', final:{taskId}}
+    //   4. 错误 → {kind:'error'}(A2AError);取消由 ctx.signal.abort() 传导中断 SDK 流
+    // 本期骨架不发起真实 SDK 调用;配置齐备时返回空事件流(消息随即 consumed)。
+    void request
+    void ctx
+  }
+}

package/server/services/workshop/agents/factory.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent 实现工厂 — 按 harness 装配 AgentInterface。
+ * mock:进程内 mock(联调/测试);omp:真实 omp 子进程(默认推荐);
+ * claude:Claude Agent SDK(待接入);未知 harness 抛 UNKNOWN_HARNESS。
+ * 权威契约见 docs/superpowers/plans/2026-08-13-agent-workshop-multi-agent.md 核心契约块 T5。
+ */
+import { AppError } from '../../../utils/errors'
+import type { AgentInfo, AgentInterface } from './agent-interface'
+import { MockAgentImpl } from './mock-agent'
+import { OmpRpcAgentImpl } from './omp-agent'
+import { ClaudeSdkAgentImpl } from './claude-agent'
+
+export function createAgentImpl(agent: AgentInfo): AgentInterface {
+  switch (agent.harness) {
+    case 'mock':
+      return new MockAgentImpl(agent.config)
+    case 'omp':
+      return new OmpRpcAgentImpl({ ...agent.config, agentId: agent.id, name: agent.name, role: agent.role, channelId: agent.channelId })
+    case 'claude':
+      return new ClaudeSdkAgentImpl(agent.config)
+    default:
+      throw new AppError(400, 'UNKNOWN_HARNESS', `未知 harness: ${agent.harness}`)
+  }
+}

package/server/services/workshop/agents/harness-process.ts

@@ -0,0 +1,158 @@
+/**
+ * Harness 进程注册表 — 运行时资源监控的中心事实源。
+ *
+ * 每个 harness 子进程(当前:omp `--mode rpc`)在 spawn 时登记、在退出/被杀时标记,
+ * 供「运行时资源监控」列出全部已启动的 harness 进程(含已脱离 runtimes 的孤儿进程),
+ * 并支持按 PID 强制终止(Windows: taskkill /T /F 杀进程树;POSIX: 进程组 SIGKILL)。
+ *
+ * 定位:模块级单例,harnest 装配(OmpRpcAgentImpl)登记,manager 监控层读取;
+ * 不依赖 manager,避免循环依赖。
+ */
+import { createLogger } from '../logger'
+import { spawn } from 'node:child_process'
+
+const log = createLogger('workshop.harness')
+
+/** 注册表条目:一个已启动(或已退出)的 harness 子进程 */
+export interface HarnessProcessEntry {
+  pid: number
+  harness: string
+  /** 可执行文件(诊断用) */
+  command: string
+  /** 完整 argv(诊断用) */
+  args: string[]
+  /** 归属 agent;未绑定(孤立/尚未装配完成)为 null */
+  agentId: string | null
+  channelId: string | null
+  name: string | null
+  role: 'lead' | 'worker' | null
+  startedAt: number
+  alive: boolean
+  exitCode: number | null
+  exitedAt: number | null
+}
+
+/** pid → 条目(模块级单例) */
+const registry = new Map<number, HarnessProcessEntry>()
+
+/** spawn 后登记(pid 无效直接忽略) */
+export function registerHarnessProcess(
+  pid: number,
+  meta: { harness: string, command: string, args?: string[] },
+): void {
+  if (!Number.isInteger(pid) || pid <= 0) return
+  registry.set(pid, {
+    pid,
+    harness: meta.harness,
+    command: meta.command,
+    args: meta.args ?? [],
+    agentId: null,
+    channelId: null,
+    name: null,
+    role: null,
+    startedAt: Date.now(),
+    alive: true,
+    exitCode: null,
+    exitedAt: null,
+  })
+}
+
+/** 装配完成后绑定 agent 身份(monitor 据此归属进程 ↔ runtime) */
+export function bindHarnessProcess(
+  pid: number,
+  meta: { agentId: string, channelId: string, name: string, role: 'lead' | 'worker' },
+): void {
+  const e = registry.get(pid)
+  if (!e) return
+  e.agentId = meta.agentId
+  e.channelId = meta.channelId
+  e.name = meta.name
+  e.role = meta.role
+}
+
+/** 进程退出/被杀后标记(幂等;exit 事件与 kill 路径共用) */
+export function markHarnessProcessExit(pid: number, exitCode: number | null): void {
+  const e = registry.get(pid)
+  if (!e) return
+  e.alive = false
+  e.exitCode = exitCode
+  e.exitedAt = Date.now()
+}
+
+export function listHarnessProcesses(): HarnessProcessEntry[] {
+  return [...registry.values()]
+}
+
+/** 某 agent 仍存活(未退出)的进程——terminate 兜底:runtime 已卸载但进程残留时按 agentId 强杀 */
+export function listAliveHarnessProcessesByAgent(agentId: string): HarnessProcessEntry[] {
+  return [...registry.values()].filter(e => e.alive && e.agentId === agentId)
+}
+
+/** 惰性清理:退出超过 retentionMs 的条目(防泄漏,monitor 快照时调用;1min 足够监控可见性) */
+export function sweepHarnessProcesses(retentionMs = 60_000): void {
+  const now = Date.now()
+  for (const [pid, e] of registry) {
+    if (!e.alive && e.exitedAt !== null && now - e.exitedAt > retentionMs) {
+      registry.delete(pid)
+    }
+  }
+}
+
+/**
+ * OS 级进程存活探针(signal 0,不产生实际信号)。
+ * 系统休眠/强杀/崩溃后子进程的 exit 事件可能不达父进程(Node 侧 → 'exited' 仍 false),
+ * 注册表/客户端的 alive 标记会长期失真。此探针按 PID 查 OS 实际存在性来校准:
+ *  EPERM = 进程存在但无权限(仍视为存活);ESRCH = 进程已不存在;其余未知均视为不可信。
+ */
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  }
+  catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+/**
+ * 强制终止进程树(异步;taskkill 需等进程树枚举+逐个终止,同步 spawn 会阻塞事件循环数百 ms)。
+ * Windows: taskkill /pid <pid> /T /F(整棵进程树,含 omp 可能拉起的子进程);
+ * POSIX: 先按进程组(-pid)后按单进程 SIGKILL(同步 signal,无阻塞)。
+ * 立即同步标记条目为已退出(OS 层 exit 事件随后也会触发 markHarnessProcessExit);
+ * `ok` 反映终止请求是否已受理(Windows 为 taskkill 进程退出码,异步回调补记)。
+ */
+export function killHarnessProcess(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  let ok = false
+  try {
+    if (process.platform === 'win32') {
+      const child = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' })
+      child.on('exit', (code) => {
+        if (code !== 0) log.warn(`[harness] taskkill pid=${pid} 退出码 ${code}`)
+      })
+      child.on('error', () => { /* spawn 失败:保持 ok=false */ })
+      ok = true // 请求已受理;结果异步(失败仅告警,exit 事件兜底归位)
+    }
+    else {
+      try {
+        process.kill(-pid, 'SIGKILL')
+        ok = true
+      }
+      catch {
+        try {
+          process.kill(pid, 'SIGKILL')
+          ok = true
+        }
+        catch {
+          ok = false
+        }
+      }
+    }
+  }
+  catch {
+    /* 保持 ok = false */
+  }
+  markHarnessProcessExit(pid, null)
+  return ok
+}