agentworkshop 0.7.44 → 0.7.47

package/server/services/workshop/agents/adapters/omp-rpc-client/types.ts

@@ -0,0 +1,115 @@
+/**
+ * OmpRpcClient 的依赖类型与对外 DTO(原 server/services/workshop/agents/adapters/omp-rpc-client.ts 顶部模块级类型声明)。纯类型。
+ */
+
+export type RpcCommand
+  = | { id?: string, type: 'prompt', message: string, streamingBehavior?: 'steer' | 'followUp' }
+    | { id?: string, type: 'steer', message: string }
+    | { id?: string, type: 'follow_up', message: string }
+    | { id?: string, type: 'abort' }
+    | { id?: string, type: 'set_host_tools', tools: RpcHostToolDefinition[] }
+    | { id?: string, type: 'set_todos', phases: unknown[] }
+    | { id?: string, type: 'negotiate_protocol', protocolVersion: number }
+    | { id?: string, type: 'set_model', provider: string, modelId: string }
+    | { id?: string, type: 'get_state' }
+    | { id?: string, type: 'new_session' }
+    // ===== 上下文治理(70% 压缩环;协议权威 omp://rpc.md)=====
+    | { id?: string, type: 'get_session_stats' }
+    | { id?: string, type: 'compact', customInstructions?: string }
+    | { id?: string, type: 'set_auto_compaction', enabled: boolean }
+
+/** compaction 结果(compaction_end 事件 / compact 响应 data.result 共用形状) */
+export interface CompactionResult {
+  summary?: string
+  tokensBefore?: number
+  tokensAfter?: number
+  estimatedTokensAfter?: number
+}
+
+/** provider 用量(被动上下文跟踪源;message_update 等帧携带的累计值) */
+export interface RpcUsage {
+  /** input tokens ≈ 当前上下文长度(本回合 LLM 调用的 prompt 规模) */
+  input: number
+  output?: number
+  cacheRead?: number
+  at: number
+}
+/** host 工具定义(omp 端可见的工具 schema) */
+export interface RpcHostToolDefinition {
+  name: string
+  label?: string
+  description: string
+  parameters: Record<string, unknown>
+  hidden?: boolean
+}
+
+/** RPC 响应(命令执行结果) */
+export interface RpcResponse {
+  id?: string
+  type: 'response'
+  command: string
+  success: boolean
+  data?: unknown
+  error?: string
+  code?: string
+}
+
+/** omp AgentSession 事件(本项目消费的子集) */
+export interface AgentSessionEvent {
+  type: string
+  // message_update
+  assistantMessageEvent?: {
+    type: 'text_delta' | 'text_start' | 'text_end' | 'thinking_delta' | 'tool_call' | 'tool_result' | string
+    delta?: string
+    text?: string
+    toolName?: string
+    toolCallId?: string
+    [k: string]: unknown
+  }
+  message?: { role: string, content: unknown[] }
+  // agent_end
+  messages?: Array<{ role: string, content: Array<{ type: string, text?: string }> }>
+  isTerminal?: boolean
+  // tool_execution
+  toolName?: string
+  toolCallId?: string
+  [k: string]: unknown
+}
+
+/** omp 向宿主发起的 host_tool_call 请求 */
+export interface HostToolCallRequest {
+  id: string
+  toolCallId: string
+  toolName: string
+  arguments: Record<string, unknown>
+}
+
+/** 宿主工具 handler:接收 omp 的工具调用,返回结果 */
+export type HostToolHandler = (req: HostToolCallRequest) => Promise<{ text: string, isError?: boolean }>
+
+/** RPC 客户端配置 */
+export interface OmpRpcClientOptions {
+  /** omp 可执行文件路径(默认 'omp') */
+  command?: string
+  /**
+   * 输出模式:'rpc' = 纯协议(无 UI);'rpc-ui' = 协议 + UI 上下文
+   * (ask 工具 / extension_ui_request 对话框可用 —— HITL 通道;强制 noPty)。默认 'rpc'。
+   */
+  mode?: 'rpc' | 'rpc-ui'
+  /** 额外 CLI 参数 */
+  args?: string[]
+  /** 工作目录 */
+  cwd?: string
+  /** 环境变量 */
+  env?: Record<string, string>
+  /** 进程退出回调(运行时资源监控登记/标记用;pid 为 -1 表示无法取得) */
+  onExit?: (pid: number, code: number | null) => void
+}
+
+export interface PendingRequest {
+  resolve: (response: RpcResponse) => void
+  reject: (error: Error) => void
+  timer?: ReturnType<typeof setTimeout>
+}
+
+/** 流式缓冲上限(超限截断并计数,防大输出/异常流拖爆内存) */

package/server/services/workshop/agents/adapters/omp-rpc-client/usage.ts

@@ -0,0 +1,47 @@
+/**
+ * OmpRpcClientUsage —— 用量提取 / 存活核对 / 终止
+ * (拆分层,承 OmpRpcClientState;方法体与原文件逐行一致)
+ */
+import { OmpRpcClientState } from './state'
+import type { RpcUsage } from './types'
+import { isProcessAlive } from '../../harness-process'
+
+export abstract class OmpRpcClientUsage extends OmpRpcClientState {
+  /**
+   * 从帧中防御性提取累计 usage(顶层 frame.usage 或 frame.message.usage;
+   * input 兼容 input/inputTokens/promptTokens 命名;无有效 input 返回 null)。
+   */
+  protected extractUsage(frame: Record<string, unknown>): RpcUsage | null {
+    const raw = (frame.usage ?? (frame.message as Record<string, unknown> | undefined)?.usage) as Record<string, unknown> | undefined
+    if (!raw || typeof raw !== 'object') return null
+    const input = Number(raw.input ?? raw.inputTokens ?? raw.promptTokens)
+    if (!Number.isFinite(input) || input <= 0) return null
+    const output = Number(raw.output ?? raw.outputTokens)
+    const cacheRead = Number(raw.cacheRead)
+    return {
+      input,
+      output: Number.isFinite(output) ? output : undefined,
+      cacheRead: Number.isFinite(cacheRead) ? cacheRead : undefined,
+      at: Date.now(),
+    }
+  }
+
+  /**
+   * OS 级存活校准(系统休眠/强杀后 exit 事件可能不达,alive 会失真):
+   * 按 PID 探 OS 实际存在性,进程已死则收敛为已退出(与 exit 事件同路径:
+   * onExit 登记、拒绝 pending、广播 __process_exit__),在途回合据此归位,
+   * 后续 ensureClient 得以重生子进程。幂等;进程健在/未 spawn 时无操作。
+   */
+  reconcile(): boolean {
+    const pid = this.child?.pid
+    if (!pid || this.exited || this.disposed) return true
+    if (isProcessAlive(pid)) return true
+    this.handleExit(null)
+    return false
+  }
+
+  /** 强制终止子进程(不等优雅退出;进程树终止由监控层 killHarnessProcess 负责) */
+  kill(): void {
+    this.child?.kill('SIGKILL')
+  }
+}

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

@@ -40,6 +40,19 @@ export interface AgentRunRequest {
 export interface AgentWorkspace {
   /** 列出本 Channel 同事 */
   listAgents(): Promise<AgentInfo[]>
+  /**
+   * (仅 lead)把一次**人类请求**升级为可追踪的根任务,归属 Lead 自己。
+   *
+   * 为什么需要它:`dispatch_task` 强制要求 `parent_task_id`,因此从**群聊**收到的
+   * 专业请求原先无法被拆解 —— Lead 只能回一句话,或干等人类另去"任务"入口再提交一次。
+   * 有了本方法,Lead 可以把群聊里的一句需求登记成根任务,再按需 dispatch 子任务、
+   * 逐项验收、以有序总结 complete 根任务,最后把结论回给提问者。
+   *
+   * 语义:创建 SUBMITTED 根任务(assignee = 调用方 lead 自己,creator = lead),
+   * **不**向自己投递 assign 消息(lead 正在回合内,无需自我唤醒;后续由调度器按
+   * "lead 名下未规划根任务"触发 supervise 继续分解或直接作答)。
+   */
+  submitTask(input: { title: string, description?: string, parts?: Part[], sourceChatMessageId?: string, sourceChatDeliveryId?: string }): Promise<WorkspaceTask>
   /** 任务分发(仅 lead;创建子任务并指派) */
   dispatchTask(input: { parentTaskId?: string, assigneeId: string, title: string, description?: string, parts?: Part[], routeReason?: string }): Promise<WorkspaceTask>
   /** 查看同 Channel 任务列表(含同事) */
@@ -85,7 +98,10 @@ export interface AgentWorkspace {
     activeTasks: Array<{ id: string, title: string, state: string }>
     recentCompleted: Array<{ title: string }>
   }>
-  /** (全员)跨团队共享记忆检索:其他 channel 的 __team__ 公共域,只读,带团队归属。同步返回,同 listOtherTeams */
+  /**
+   * 跨 Channel 共享记忆检索(**仅 Leader**;其他 Channel 的 __team__ 公共域,只读)。
+   * §7.4:DTO 必须自描述来源 Channel / root / task / 时间 / 可见性。
+   */
   searchOtherTeamsMemory(input: { query: string, limit?: number }): Array<{
     channelId: string
     channelName: string
@@ -93,6 +109,9 @@ export interface AgentWorkspace {
     content: string
     importance: number
     createdAt: string
+    taskId?: string | null
+    rootId?: string | null
+    visibility?: 'channel-shared' | 'private' | 'cross-channel'
   }>
   /**
    * 拒绝指派给自己的任务(能力/范畴不匹配):任务置 FAILED(调度器改派他人),
@@ -120,6 +139,11 @@ export interface AgentWorkspace {
     createdAt: string
     score: number
     source: 'private' | 'shared'
+    /** §7.4 来源定位:Channel / root / task / 可见性 */
+    channelId?: string
+    taskId?: string | null
+    rootId?: string | null
+    visibility?: 'channel-shared' | 'private' | 'cross-channel'
   }>>
   /**
    * 记忆主动沉淀(save_memory 工具桥):Agent 作业中总结的可复用经验/结论。
@@ -180,6 +204,9 @@ export interface SupervisionSnapshot {
   now: number
   /** 全 channel 任务摘要 */
   tasks: WorkspaceTask[]
+  /** FIFO 根任务协调：只有 activeRoot 可被 Lead 规划，queued roots 只读 */
+  activeRootId?: string | null
+  queuedRootIds?: string[]
   /** 成员状态(含队列上下文与实时进度,供 lead 做最优调配与停滞识别) */
   members: {
     agentId: string
@@ -209,11 +236,19 @@ export interface SupervisionSnapshot {
   mail?: ChannelMail[]
 }
 
+export interface SupervisionOptions {
+  signal?: AbortSignal
+  /** Watchdog threshold reached; must be observational and must not abort the turn. */
+  onWatchdog?: (at: number) => void
+}
+
 /** 调度决策: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: 'wait', rootId?: string, reason?: string }
+    | { kind: 'guide', taskId: string, toAgentId: string, message: string }
+    | { kind: 'reassign', taskId: string, toAgentId: string, reason?: string }
+    | { kind: 'cancel', taskId: string, reason?: 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 }
@@ -230,7 +265,9 @@ export interface AgentInterface {
   /** 标准流式返回:输入一次,产出统一事件流 */
   run(request: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent>
   /** lead 调度决策(可选,仅 role='lead' 时被 SchedulerLoop 调用) */
-  supervise?(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]>
+  supervise?(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: SupervisionOptions): Promise<SupervisionDecision[]>
+  /** Supervision watchdog/hard-stop policy; watchdog never implies task cancel. */
+  getSupervisionPolicy?(): { watchdogMs: number, hardTimeoutMs: number }
   /**
    * 实时消息注入:将文本注入正在运行的 omp 会话。
    * 返回送达模式:'steer' = 已注入流式会话(同轮可见,可安全标记消费);
@@ -240,6 +277,17 @@ export interface AgentInterface {
   steer?(text: string): Promise<'steer' | 'deferred'>
   init?(config: { agent: AgentInfo, channelId: string }): Promise<void>
   dispose?(): Promise<void>
+  /**
+   * 可选:harness 会话身份(设计文档 §2.4 `session_id / thread_id`)。
+   * 无会话概念的引擎(一次性 CLI)返回 null —— 平台据此如实展示连续性能力。
+   */
+  getSessionId?(): string | null
+  /**
+   * 可选:消费一次「上次 Harness 重建原因」(§6.2 lastRestartReason)。
+   * harness 在重建 client/进程时记录原因(PROMPT_FAIL / RPC_BROKEN / PROCESS_EXIT /
+   * TURN_STALLED / SERVER_RESTART),运行时取出后清空,用于连续性审计与共享记忆。
+   */
+  takeHarnessRestartReason?(): string | null
   /**
    * 可选:harness 进程资源信息(运行时资源监控用)。
    * 进程内 harness(mock/claude)无外部进程 → 不实现返回 null。

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

@@ -25,6 +25,7 @@ import type {
   AgentRunContext,
   AgentRunRequest,
   SupervisionDecision,
+  SupervisionOptions,
   SupervisionSnapshot,
 } from './agent-interface'
 import { createSessionState, dispatchHostTool, type HostToolBridgeContext, type HostToolSessionState } from './host-tool-bridge'
@@ -51,6 +52,8 @@ export interface BaseAgentIdentity {
  */
 export interface BaseAgentConfigView {
   superviseTimeoutMs?: number
+  superviseWatchdogMs?: number
+  superviseHardTimeoutMs?: number
   systemPromptPrefix?: string
   scenarioPrompt?: string
 }
@@ -136,13 +139,27 @@ export abstract class BaseAgentImpl implements AgentInterface {
   async* run(request: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent> {
     if (!this.workspace) this.workspace = ctx.workspace
     const kind = request.message.metadata?.['x-aw-task-kind']
-    if (kind === 'assign' && ctx.role === 'worker') {
-      yield* this.workerTurn(request, ctx)
-      return
+    const sourceChatMessageId = typeof request.message.metadata?.['x-aw-source-chat-message-id'] === 'string'
+      ? String(request.message.metadata['x-aw-source-chat-message-id'])
+      : null
+    const sourceChatDeliveryId = typeof request.message.metadata?.['x-aw-delivery-id'] === 'string'
+      ? String(request.message.metadata['x-aw-delivery-id'])
+      : null
+    this.toolState.sourceChatMessageId = sourceChatMessageId
+    this.toolState.sourceChatDeliveryId = sourceChatDeliveryId
+    try {
+      if (kind === 'assign' && ctx.role === 'worker') {
+        yield* this.workerTurn(request, ctx)
+        return
+      }
+      if (!kind && (request.fromAgentId || request.message.metadata?.['x-aw-from-label'])) {
+        yield* this.peerTurn(request, ctx)
+        return
+      }
     }
-    if (!kind && (request.fromAgentId || request.message.metadata?.['x-aw-from-label'])) {
-      yield* this.peerTurn(request, ctx)
-      return
+    finally {
+      this.toolState.sourceChatMessageId = null
+      this.toolState.sourceChatDeliveryId = null
     }
   }
 
@@ -157,7 +174,7 @@ export abstract class BaseAgentImpl implements AgentInterface {
   /** supervise 互斥位(子类 supervise 实现与本字段共享同一实例字段,故为 protected;纯可见性修饰,无运行时差异) */
   protected supervising = false
 
-  async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
+  async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: SupervisionOptions): Promise<SupervisionDecision[]> {
     if (this.supervising) return []
     if (!this.workspace) this.workspace = ctx.workspace
     const prompt = supervisePrompt({
@@ -170,7 +187,7 @@ export abstract class BaseAgentImpl implements AgentInterface {
     })
     this.supervising = true
     try {
-      const events = await this.collectTurnEvents(prompt, this.superviseTimeoutMs(), opts?.signal)
+      const events = await this.collectTurnEvents(prompt, this.getSupervisionPolicy().hardTimeoutMs, opts?.signal)
       let text = ''
       for (const e of events) {
         if (e.kind === 'artifact') {
@@ -188,6 +205,17 @@ export abstract class BaseAgentImpl implements AgentInterface {
     }
   }
 
+  getSupervisionPolicy(): { watchdogMs: number, hardTimeoutMs: number } {
+    const configured = Number(this.configRecord().superviseTimeoutMs)
+    const watchdog = Number(this.configRecord().superviseWatchdogMs)
+    const watchdogMs = Number.isFinite(watchdog) && watchdog > 0
+      ? watchdog
+      : (Number.isFinite(configured) && configured > 0 ? configured : 90_000)
+    const hard = Number(this.configRecord().superviseHardTimeoutMs)
+    const hardTimeoutMs = Number.isFinite(hard) && hard > 0 ? hard : Math.max(300_000, watchdogMs * 4)
+    return { watchdogMs, hardTimeoutMs }
+  }
+
   protected superviseTimeoutMs(): number {
     const v = Number(this.configRecord().superviseTimeoutMs)
     return Number.isFinite(v) && v > 0 ? v : 150_000

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

@@ -555,6 +555,11 @@ export class ClaudeSdkAgentImpl extends BaseAgentImpl implements AgentInterface
       options: ['allow', 'reject'],
       createdAt: new Date().toISOString(),
       expiresAt: null,
+      // v17:审批语义 + 原生请求/会话标识(claude SDK 进程内会话;无子进程 pid)
+      requestType: 'approval',
+      nativeRequestId: id,
+      sessionId: this.sessionId ?? '',
+      harness: 'claude',
     })
     const timeoutMs = harnessSettings().hitl_timeout_ms
     return await new Promise<PermissionVerdict>((resolve) => {

package/server/services/workshop/agents/codex-agent/client.ts

@@ -0,0 +1,170 @@
+/**
+ * CodexAgentImplClient —— codex 子进程与客户端管理
+ * (拆分层,承 CodexAgentImplHitl;方法体与原文件逐行一致)
+ */
+import { CodexAgentImplHitl } from './hitl'
+import type { AgentRunContext } from '../agent-interface'
+import { StdioJsonRpcClient } from '../adapters/stdio-jsonrpc'
+import { bindHarnessProcess, markHarnessProcessExit, registerHarnessProcess } from '../harness-process'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { generateMcpBridgeEnv } from '../harness-env'
+import { harnessSettings } from '../../settings'
+import { join } from 'node:path'
+import { log } from './helpers'
+import { randomUUID } from 'node:crypto'
+import { tmpdir } from 'node:os'
+
+export abstract class CodexAgentImplClient extends CodexAgentImplHitl {
+  protected async ensureClient(ctx: AgentRunContext): Promise<void> {
+    if (!this.workspace) this.workspace = ctx.workspace
+    if (!this.agentInfo) {
+      this.channelId = ctx.channelId
+      this.agentRole = ctx.role
+      this.refreshIdentity()
+    }
+    if (this.client?.alive && this.threadId) return
+    if (this.client && !this.client.alive) {
+      this.client = null
+      this.threadId = null
+    }
+    this.clientStarting ??= this.startClient().finally(() => {
+      this.clientStarting = null
+    })
+    await this.clientStarting
+  }
+
+  protected async startClient(): Promise<void> {
+    const command = this.config.command ?? harnessSettings().codex_command
+    const client = new StdioJsonRpcClient({
+      name: 'codex',
+      command,
+      args: [...(this.config.args ?? []), 'app-server'],
+      cwd: this.config.cwd ?? process.cwd(),
+      env: generateMcpBridgeEnv({
+        agentId: this.selfAgentId,
+        token: this.config.token,
+        baseUrl: this.config.baseUrl,
+        bridgePath: this.config.mcpBridgePath,
+        extra: this.config.codexHome ? { CODEX_HOME: this.config.codexHome } : {},
+      }).engineEnv,
+      requestTimeoutMs: 60_000,
+    })
+    const pidRef = { pid: undefined as number | undefined }
+    client.onExit((code) => {
+      if (pidRef.pid) markHarnessProcessExit(pidRef.pid, code)
+      this.threadId = null
+      log.warn(`[CodexAgent:${this.selfAgentId}] codex app-server 退出(code=${code});下回合自动重生`)
+    })
+    await client.start()
+    pidRef.pid = client.pid
+    if (client.pid) {
+      registerHarnessProcess(client.pid, { harness: 'codex', command, args: ['app-server'] })
+      bindHarnessProcess(client.pid, { agentId: this.selfAgentId, channelId: this.channelId, name: this.agentName, role: this.agentRole })
+    }
+
+    // 握手
+    await client.request('initialize', {
+      clientInfo: { name: 'agentworkshop', title: 'AgentWorkShop', version: '0.8.0' },
+    }, 30_000)
+    client.notify('initialized', {})
+
+    // MCP 桥装配(per-agent CODEX_HOME 的 config.toml [mcp_servers.aw])
+    this.writeCodexHomeConfig()
+
+    // 建会话
+    const result = await client.request('thread/start', {
+      ...(this.config.model ? { model: this.config.model } : {}),
+      cwd: this.config.cwd ?? process.cwd(),
+      approvalPolicy: this.config.approvalPolicy ?? 'on-request',
+      sandbox: this.config.sandbox ?? 'workspace-write',
+    }, 60_000) as Record<string, unknown>
+    const thread = (result?.thread ?? result) as Record<string, unknown>
+    this.threadId = typeof thread?.id === 'string' ? thread.id : null
+    if (!this.threadId) throw new Error('codex thread/start 未返回 thread id')
+
+    // 事件监听挂接(通知在 streamTurn 内按回合订阅;此处仅挂请求处理器)
+    client.onRequest((req) => {
+      if (req.method === 'item/commandExecution/requestApproval' || req.method === 'item/fileChange/requestApproval') {
+        const p = (req.params ?? {}) as Record<string, unknown>
+        this.registerApprovalHitl(req.id, String(p.itemId ?? randomUUID()), req.method === 'item/fileChange/requestApproval' ? 'file' : 'command', p)
+      }
+      else if (req.method === 'tool/requestUserInput') {
+        const p = (req.params ?? {}) as Record<string, unknown>
+        this.registerUserInputHitl(req.id, p)
+      }
+      else {
+        client.respondError(req.id, -32601, `方法不存在: ${req.method}`)
+      }
+    })
+
+    this.client = client
+  }
+
+  /**
+   * per-agent CODEX_HOME config.toml:注册 MCP 桥(required=true,桥挂了宁可失败)。
+   * 已有 config.toml(从全局目录种子化复制)→ 追加本段(保留用户的 provider/model
+   * 配置,自定义网关/密钥不丢失);全新目录 → 独立写入。
+   *
+   * 无条件种子化(不再仅当 effort 配置时才挂桥):MCP 桥是 codex worker 的 host
+   * 工具面(complete_task/ops_log/…)唯一入口;不挂桥的实例模型只能拿自带 shell
+   * 乱翻工作区,永远调不到 complete_task → 任务停滞被看门狗回收
+   * (实测 codex 任务终态 CANCELED、交付物却只落在频道消息里的根因)。
+   */
+  protected writeCodexHomeConfig(): void {
+    let home = this.config.codexHome
+    if (!home) {
+      // 自动种子化 per-agent CODEX_HOME(拷贝全局凭据/网关配置,保登录与自定义
+      // provider;追加 MCP 段 + 顶部 effort)
+      home = join(tmpdir(), `aw-codex-${this.selfAgentId.slice(0, 8)}`)
+      this.config.codexHome = home
+      for (const f of ['auth.json', 'config.toml', 'cc-switch-model-catalog.json']) {
+        try {
+          const src = join(process.env.HOME ?? process.env.USERPROFILE ?? '', '.codex', f)
+          if (existsSync(src)) copyFileSync(src, join(home, f))
+        }
+        catch { /* 单文件缺失忽略 */ }
+      }
+    }
+    try {
+      mkdirSync(home, { recursive: true })
+      const configFile = join(home, 'config.toml')
+      const env = generateMcpBridgeEnv({ agentId: this.selfAgentId, token: this.config.token, baseUrl: this.config.baseUrl, bridgePath: this.config.mcpBridgePath })
+      const envLines = Object.entries(env.bridgeEnv).map(([k, v]) => `      ${k} = "${v}"`).join('\n')
+      const section = [
+        ``,
+        `[mcp_servers.aw]`,
+        `command = ${JSON.stringify(process.execPath)}`,
+        `args = [${JSON.stringify(join(process.env.AW_PACKAGE_ROOT ?? process.cwd(), 'server', 'harness', 'aw-mcp-bridge.mjs'))}]`,
+        `required = true`,
+        ``,
+        `[mcp_servers.aw.env]`,
+        envLines,
+        ``,
+      ].join('\n')
+      // effort 走 TOML 顶层键(model_reasoning_effort):必须位于任何 [table] 之前 → 顶部插入
+      const effortLine = this.config.effort
+        ? `model_reasoning_effort = ${JSON.stringify(this.config.effort)}
+`
+        : ''
+      if (existsSync(configFile)) {
+        const existing = readFileSync(configFile, 'utf-8')
+        const withoutDup = this.config.effort
+          ? existing.replace(/^model_reasoning_effort = .*\n?/m, '')
+          : existing
+        if (withoutDup.includes('[mcp_servers.aw]')) {
+          if (effortLine && !withoutDup.startsWith(effortLine.trim())) {
+            writeFileSync(configFile, effortLine + withoutDup, 'utf-8')
+          }
+          return
+        }
+        writeFileSync(configFile, effortLine + withoutDup + section, 'utf-8')
+      }
+      else {
+        writeFileSync(configFile, effortLine + section, 'utf-8')
+      }
+    }
+    catch (err) {
+      log.warn(`[CodexAgent:${this.selfAgentId}] CODEX_HOME config 写入失败(信任全局配置):`, err instanceof Error ? err.message : err)
+    }
+  }
+}

package/server/services/workshop/agents/codex-agent/core.ts

@@ -0,0 +1,119 @@
+/**
+ * CodexAgentImplCore —— 字段 / 构造 / 配置面 / 进程面
+ * (拆分层,承 BaseAgentImpl;方法体与原文件逐行一致)
+ *
+ * 本层还声明了 2 个跨层契约抽象方法(原类已有基类,无法再挂 contracts.ts)。
+ */
+import { BaseAgentImpl } from '../base-agent'
+import type { AepHitlQuestion } from '../../../../../shared/workshop-protocol'
+import type { AgentContextStats } from '../../types/task'
+import type { AgentInfo, AgentRunContext } from '../agent-interface'
+import type { BaseAgentConfigView } from '../base-agent'
+import type { CodexAgentConfig } from './types'
+import type { StdioJsonRpcClient } from '../adapters/stdio-jsonrpc'
+import { killHarnessProcess, markHarnessProcessExit } from '../harness-process'
+
+export abstract class CodexAgentImplCore extends BaseAgentImpl {
+  // ── 跨层能力契约(由后面的层实现;见本文件头部说明)──
+  protected abstract ensureClient(ctx: AgentRunContext): Promise<void>
+  protected abstract respondUserInput(
+    rpcId: string | number,
+    id: string,
+    outcome: { cancelled?: boolean, value?: string, answers?: Array<{ id?: string, answer: string }> },
+  ): Promise<void>
+
+  protected readonly config: CodexAgentConfig
+  protected agentInfo: AgentInfo | null = null
+  // 不要重新声明 bridgeCtx / agentRole(由 BaseAgentImpl 持有)。
+  // 子类字段初始化器在 super() 之后执行,会用空 identity 遮蔽基类已装配好的 bridgeCtx,
+  // 使 host tool 桥的 agentId 恒为 '' → 按 agentId 的鉴权全部误判(节点绑定/工业工具)。
+  // 同理 agentRole 会被重置为 'worker',lead 身份丢失。
+
+  protected client: StdioJsonRpcClient | null = null
+  protected clientStarting: Promise<void> | null = null
+  protected threadId: string | null = null
+  protected turnId: string | null = null
+
+  // 回合状态
+  protected turnActive = false
+  protected deltaBuf = ''
+  protected deltaTimer: ReturnType<typeof setTimeout> | null = null
+  protected lastUsage: { input: number, at: number } | null = null
+  protected compacting = false
+  protected lastCompactAt = 0
+  /**
+   * 待应答 HITL(approval request id → JSON-RPC id)。
+   * v17:`type` 区分 approval 与 question —— 二者**原生应答载荷不同**
+   * (approval → `{decision: accept|decline|cancel}`;question → `{answers:[…]}`),
+   * 原先只有一张表且 respondHitl 恒发 `{decision}`,导致 tool/requestUserInput
+   * 的提问只能靠超时取消(§13.5 必修复项)。
+   */
+  protected pendingApprovals = new Map<string, {
+    rpcId: string | number
+    timer: ReturnType<typeof setTimeout> | null
+    type: 'approval' | 'question'
+    /** question 型:全量问题(多问题按序回传 answers[]) */
+    questions: AepHitlQuestion[]
+  }>()
+
+  constructor(config: Record<string, unknown> = {}) {
+    super({
+      agentId: typeof config.agentId === 'string' ? config.agentId : '',
+      name: typeof config.name === 'string' ? config.name : undefined,
+      role: config.role === 'lead' ? 'lead' : 'worker',
+      channelId: typeof config.channelId === 'string' ? config.channelId : '',
+    })
+    this.config = config as CodexAgentConfig
+  }
+
+  protected get harnessId(): string {
+    return 'codex'
+  }
+
+  protected configRecord(): BaseAgentConfigView {
+    return this.config
+  }
+
+  async dispose(): Promise<void> {
+    const client = this.client
+    this.client = null
+    this.threadId = null
+    if (client) {
+      const pid = client.pid
+      await client.dispose().catch(() => {})
+      if (pid) markHarnessProcessExit(pid, null)
+    }
+    for (const [id, p] of this.pendingApprovals) {
+      if (p.timer) clearTimeout(p.timer)
+      this.pendingApprovals.delete(id)
+    }
+  }
+
+  getProcessInfo(): { pid: number, alive: boolean, command: string } | null {
+    const client = this.client
+    const pid = client?.pid
+    if (!pid || !client) return null
+    return { pid, alive: client.alive, command: 'codex app-server' }
+  }
+
+  killProcess(): void {
+    const pid = this.client?.pid
+    if (pid) killHarnessProcess(pid)
+    else this.client?.kill()
+  }
+
+  reconcileProcess(): void {
+    this.client?.reconcile()
+  }
+
+  getContextStats(): AgentContextStats | null {
+    if (!this.lastUsage) return null
+    const window = this.config.contextWindow ?? null
+    return {
+      usedTokens: this.lastUsage.input,
+      contextWindow: window,
+      percent: window && window > 0 ? Math.min(1, this.lastUsage.input / window) : null,
+      compacting: this.compacting,
+    }
+  }
+}

package/server/services/workshop/agents/codex-agent/facade.ts

@@ -0,0 +1,8 @@
+/**
+ * CodexAgentImpl —— 组合各分层后的最终类(可见性/继承/实现接口与拆分前一致)
+ * + 原文件类体之后引用本类的模块级代码(单例/工厂/广播装配)。
+ */
+import { CodexAgentImplClient } from './client'
+import type { AgentInterface } from '../agent-interface'
+
+export class CodexAgentImpl extends CodexAgentImplClient implements AgentInterface {}