agentworkshop 0.7.27 → 0.7.33

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

@@ -1,822 +1,729 @@
-/**
- * CodexAgentImpl — OpenAI Codex CLI(app-server)harness 的 AgentInterface 实现。
- *
- * 进程模型:每 Agent 一个 `codex app-server` 子进程(stdio NDJSON JSON-RPC v2,
- * lazy spawn 跨消息复用);thread/start 建会话,turn/start 驱动回合。
- *
- *  - prompt/工具面与 omp 全引擎同源(prompt-builder / host-tool-bridge);
- *    工具经 stdio MCP 桥注入(config.toml 由 impl 装配 [mcp_servers.aw])
- *  - 事件映射:item/agentMessage/delta → delta;item/started → 🔧 status;
- *    turn/completed → artifact + done / error(codexErrorInfo 结构化)
- *  - HITL:item/commandExecution|fileChange/requestApproval(server→client 请求)
- *    → hitl-registry 登记 → respondHitl 应答(decision: accept/decline/cancel)
- *  - steer:turn 运行中 → turn/steer;无 active turn → 'deferred'
- *  - 上下文治理:thread/tokenUsage/updated 被动跟踪;越阈值 → thread/compact/start
- *
- * 协议权威:github.com/openai/codex codex-rs/app-server/README.md(v0.149 实测)。
- */
-import { createLogger } from '../logger'
-import { randomUUID } from 'node:crypto'
-import { join } from 'node:path'
-import { mkdirSync, writeFileSync, existsSync, readFileSync, copyFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import type {
-  AgentEvent,
-  AgentInterface,
-  AgentInfo,
-  AgentRunContext,
-  AgentRunRequest,
-  SupervisionDecision,
-  SupervisionSnapshot,
-} from './agent-interface'
-import type { AgentContextStats } from '../types/task'
-import { registerHarnessProcess, bindHarnessProcess, markHarnessProcessExit, killHarnessProcess } from './harness-process'
-import { createSessionState, dispatchHostTool } from './host-tool-bridge'
-import {
-  contextPrefix as buildContextPrefix,
-  createRosterCache,
-  extractJsonArray,
-  peerPrompt,
-  supervisePrompt,
-  systemManual,
-  toolArgsPreview,
-  workerPrompt,
-} from './prompt-builder'
-import { getHitlRegistry } from './hitl-registry'
-import { harnessSettings } from '../settings'
-import { StdioJsonRpcClient } from './adapters/stdio-jsonrpc'
-import { generateMcpBridgeEnv } from './harness-env'
-
-const log = createLogger('workshop.codex')
-
-export interface CodexAgentConfig {
-  /** codex 可执行文件(默认取 harness.codex_command 设置) */
-  command?: string
-  /** 额外 CLI 参数(app-server 之前) */
-  args?: string[]
-  cwd?: string
-  /** 模型(如 gpt-5.2) */
-  model?: string
-  /** 审批策略(默认 on-request:沙箱内自由,越界请求审批 → HITL) */
-  approvalPolicy?: 'untrusted' | 'on-request' | 'never'
-  /** 沙箱(默认 workspace-write) */
-  sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access'
-  /** CODEX_HOME(缺省进程环境;配置隔离/多账户时按 agent 指定;effort 未指定 home 时自动种子化) */
-  codexHome?: string
-  /** 思考 effort(model_reasoning_effort;需 CODEX_HOME 配置面,未指定 home 时自动种子化) */
-  effort?: string
-  /** 上下文窗口(usage 百分比计算) */
-  contextWindow?: number
-  /** 压缩阈值(0-1,默认 0.7) */
-  compactThreshold?: number
-  promptTimeoutMs?: number
-  superviseTimeoutMs?: number
-  systemPromptPrefix?: string
-  scenarioPrompt?: string
-  agentId?: string
-  name?: string
-  role?: 'lead' | 'worker'
-  channelId?: string
-  token?: string
-  baseUrl?: string
-  mcpBridgePath?: string
-}
-
-export class CodexAgentImpl implements AgentInterface {
-  private readonly config: CodexAgentConfig
-  private workspace: AgentRunContext['workspace'] | null = null
-  private agentInfo: AgentInfo | null = null
-  private readonly toolState = createSessionState()
-  private readonly bridgeCtx = {
-    identity: { agentId: '', channelId: '', role: 'worker' as 'lead' | 'worker', name: 'agent' },
-    state: this.toolState,
-    getWorkspace: () => this.workspace,
-  }
-
-  private roster = createRosterCache({ selfAgentId: '', listAgents: async () => [] })
-
-  private selfAgentId = ''
-  private agentName = 'agent'
-  private agentRole: 'lead' | 'worker' = 'worker'
-  private channelId = ''
-
-  private client: StdioJsonRpcClient | null = null
-  private clientStarting: Promise<void> | null = null
-  private threadId: string | null = null
-  private turnId: string | null = null
-
-  // 回合状态
-  private turnActive = false
-  private deltaBuf = ''
-  private deltaTimer: ReturnType<typeof setTimeout> | null = null
-  private lastUsage: { input: number, at: number } | null = null
-  private compacting = false
-  private lastCompactAt = 0
-  /** 待应答审批(approval request id → JSON-RPC id) */
-  private pendingApprovals = new Map<string, { rpcId: string | number, timer: ReturnType<typeof setTimeout> | null }>()
-
-  constructor(config: Record<string, unknown> = {}) {
-    this.config = config as CodexAgentConfig
-    this.selfAgentId = this.config.agentId ?? ''
-    this.agentName = this.config.name ?? 'agent'
-    this.agentRole = this.config.role ?? 'worker'
-    this.channelId = this.config.channelId ?? ''
-    this.refreshIdentity()
-  }
-
-  private refreshIdentity(): void {
-    this.bridgeCtx.identity = { agentId: this.selfAgentId, channelId: this.channelId, role: this.agentRole, name: this.agentName }
-    this.roster = createRosterCache({
-      selfAgentId: this.selfAgentId,
-      listAgents: async () => this.workspace?.listAgents() ?? [],
-    })
-  }
-
-  async init(input: { agent: AgentInfo, channelId: string }): Promise<void> {
-    this.agentInfo = input.agent
-    this.channelId = input.channelId
-    this.agentName = input.agent.name
-    this.agentRole = input.agent.role
-    this.selfAgentId = input.agent.id
-    this.refreshIdentity()
-  }
-
-  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()
-  }
-
-  dispatchHostTool(toolName: string, args: Record<string, unknown>): Promise<{ text: string, isError?: boolean }> {
-    return dispatchHostTool(this.bridgeCtx, { toolName, arguments: args })
-  }
-
-  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,
-    }
-  }
-
-  /** 实时注入:turn 运行中 → turn/steer;否则 'deferred'(消息保持 pending) */
-  async steer(text: string): Promise<'steer' | 'deferred'> {
-    const client = this.client
-    if (!client?.alive || !this.threadId || !this.turnActive) return 'deferred'
-    try {
-      await client.request('turn/steer', {
-        threadId: this.threadId,
-        input: [{ type: 'text', text }],
-      }, 15_000)
-      return 'steer'
-    }
-    catch {
-      // 无 active turn / 引擎拒绝 → 消息保持 pending 由消费循环处理
-      return 'deferred'
-    }
-  }
-
-  /** HITL 应答:审批请求 → JSON-RPC 应答(decision) */
-  async respondHitl(kind: string, id: string, outcome: {
-    confirmed?: boolean
-    cancelled?: boolean
-    value?: string
-    response?: string
-    comment?: string
-  }): Promise<void> {
-    if (kind !== 'codex-approval') return
-    const pending = this.pendingApprovals.get(id)
-    if (!pending) throw new Error(`待办不存在或已处理: ${id}`)
-    const client = this.client
-    if (!client) throw new Error('codex 会话已关闭')
-    const decision = outcome.cancelled === true
-      ? 'cancel'
-      : outcome.confirmed === true ? 'accept' : 'decline'
-    client.respond(pending.rpcId, { decision })
-    if (pending.timer) clearTimeout(pending.timer)
-    this.pendingApprovals.delete(id)
-    getHitlRegistry().resolve(kind, id, decision === 'cancel' ? 'cancelled' : 'answered')
-  }
-
-  /** 上下文治理(post-settle):越阈值 → thread/compact/start */
-  async onTurnSettled(): Promise<void> {
-    const client = this.client
-    if (!client?.alive || !this.threadId || this.compacting) return
-    const stats = this.getContextStats()
-    const threshold = this.config.compactThreshold ?? 0.7
-    if (!stats?.percent || stats.percent < threshold) return
-    if (Date.now() - this.lastCompactAt < 5 * 60_000) return
-    this.compacting = true
-    this.lastCompactAt = Date.now()
-    try {
-      await client.request('thread/compact/start', { threadId: this.threadId }, 30_000)
-      log.info(`[CodexAgent:${this.selfAgentId}] 上下文压缩已触发(percent=${(stats.percent * 100).toFixed(0)}%)`)
-    }
-    catch (err) {
-      log.warn(`[CodexAgent:${this.selfAgentId}] compact 发起失败(放行):`, err instanceof Error ? err.message : err)
-    }
-    finally {
-      this.compacting = false
-    }
-  }
-
-  // ===== run / supervise =====
-
-  async* run(request: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent> {
-    const kind = request.message.metadata?.['x-aw-task-kind']
-    if (kind === 'assign' && ctx.role === 'worker') {
-      yield* this.workerRun(request, ctx)
-      return
-    }
-    if (!kind && (request.fromAgentId || request.message.metadata?.['x-aw-from-label'])) {
-      yield* this.peerMessageRun(request, ctx)
-      return
-    }
-  }
-
-  private supervising = false
-
-  async supervise(snapshot: SupervisionSnapshot, ctx: AgentRunContext, opts?: { signal?: AbortSignal }): Promise<SupervisionDecision[]> {
-    await this.ensureClient(ctx)
-    if (!this.client || !this.threadId) return []
-    if (this.supervising) return []
-    const prompt = supervisePrompt({
-      snapshot,
-      agentName: this.agentName,
-      channelId: this.channelId,
-      ctxPrefix: await this.contextPrefix(),
-      manual: systemManual(),
-      memory: ctx.memory,
-    })
-    this.supervising = true
-    try {
-      const events = await this.collectTurn(prompt, this.config.superviseTimeoutMs ?? 150_000, opts?.signal)
-      let text = ''
-      for (const e of events) {
-        if (e.kind === 'artifact') {
-          text += e.artifact.parts.map(p => 'text' in p ? p.text : '').join('')
-        }
-      }
-      const parsed = extractJsonArray(text)
-      return parsed && parsed.length > 0 ? parsed as SupervisionDecision[] : []
-    }
-    catch {
-      return []
-    }
-    finally {
-      this.supervising = false
-    }
-  }
-
-  private async* workerRun(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
-    const taskId = request.taskId ?? (request.message.metadata?.['x-aw-task-id'] as string | undefined)
-    if (!taskId) return
-    this.toolState.currentTaskId = taskId
-    try {
-      await this.ensureClient(ctx)
-      const taskText = request.message.parts.map((p) => {
-        if ('text' in p) return p.text
-        if ('data' in p) return JSON.stringify(p.data)
-        if ('url' in p) return p.url
-        if ('raw' in p) return p.raw
-        return ''
-      }).join('\n')
-      const prompt = workerPrompt({
-        agentName: this.agentName,
-        channelId: this.channelId,
-        taskId,
-        taskText,
-        memory: request.memory,
-        ctxPrefix: await this.contextPrefix(),
-        manual: systemManual(),
-      })
-      yield* this.streamTurn(prompt, taskId, this.config.promptTimeoutMs ?? 600_000, ctx.signal)
-    }
-    finally {
-      this.toolState.currentTaskId = null
-    }
-  }
-
-  private async* peerMessageRun(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
-    await this.ensureClient(ctx)
-    const msg = request.message
-    const fromId = request.fromAgentId
-      ?? (typeof msg.metadata?.['x-aw-from-label'] === 'string' ? msg.metadata['x-aw-from-label'] : undefined)
-      ?? 'unknown'
-    const requireReply = msg.metadata?.['x-aw-require-reply'] === 'true'
-    const crossChannel = msg.metadata?.['x-aw-cross-channel'] === 'true'
-    this.toolState.replyContext = requireReply && request.fromAgentId && !crossChannel
-      ? { fromId: request.fromAgentId, messageId: msg.messageId }
-      : null
-    const msgText = msg.parts.map((p) => {
-      if ('text' in p) return p.text
-      if ('data' in p) return JSON.stringify(p.data)
-      if ('url' in p) return p.url
-      if ('raw' in p) return p.raw
-      return ''
-    }).join('\n')
-    const prompt = peerPrompt({
-      agentName: this.agentName,
-      role: this.agentRole,
-      channelId: this.channelId,
-      ctxPrefix: await this.contextPrefix(),
-      manual: systemManual(),
-      memory: request.memory,
-      fromId,
-      messageId: msg.messageId,
-      requireReply,
-      isReply: typeof msg.metadata?.['x-aw-in-reply-to'] === 'string',
-      crossChannel,
-      fromChannel: typeof msg.metadata?.['x-aw-from-channel'] === 'string' ? String(msg.metadata['x-aw-from-channel']) : '',
-      msgText,
-    })
-    yield* this.streamTurn(prompt, undefined, this.config.promptTimeoutMs ?? 600_000, ctx.signal)
-  }
-
-  private async contextPrefix(): Promise<string> {
-    return buildContextPrefix({
-      scenarioPrompt: this.config.scenarioPrompt,
-      systemPromptPrefix: this.config.systemPromptPrefix,
-      agentId: this.selfAgentId,
-      roster: await this.roster.roster(),
-    })
-  }
-
-  // ===== 回合执行 =====
-
-  /**
-   * 流式回合:turn/start → 逐事件产出(delta/status)→ turn/completed 收口。
-   * artifact 在 done 前注入(item/completed agentMessage 聚合文本)。
-   */
-  private async* streamTurn(prompt: string, taskId: string | undefined, timeoutMs: number, signal?: AbortSignal): AsyncGenerator<AgentEvent, void, unknown> {
-    const client = this.client
-    if (!client || !this.threadId) {
-      yield { kind: 'error', error: { code: 'CODEX_NOT_READY', message: 'codex 会话未就绪' } }
-      return
-    }
-    const queue: AgentEvent[] = []
-    let isDone = false
-    let resolveWait: (() => void) | null = null
-    let lastActivity = Date.now()
-    let agentText = ''
-    this.turnActive = true
-    this.turnId = null
-
-    const enqueue = (e: AgentEvent): void => {
-      if (e.kind === 'done' && !isDone) {
-        if (agentText.trim()) {
-          queue.push({
-            kind: 'artifact',
-            artifact: { artifactId: randomUUID(), name: 'output', parts: [{ text: agentText.trim() }] },
-            lastChunk: true,
-            totalChunks: 1,
-          })
-        }
-        this.turnActive = false
-      }
-      if (e.kind === 'done' || e.kind === 'error') {
-        isDone = true
-        this.turnActive = false
-        flushDelta()
-      }
-      queue.push(e)
-      lastActivity = Date.now()
-      resolveWait?.()
-      resolveWait = null
-    }
-
-    const flushDelta = (): void => {
-      if (this.deltaTimer) {
-        clearTimeout(this.deltaTimer)
-        this.deltaTimer = null
-      }
-      if (!this.deltaBuf) return
-      const text = this.deltaBuf
-      this.deltaBuf = ''
-      queue.push({ kind: 'delta', delta: { text } })
-    }
-    const pushDelta = (text: string): void => {
-      this.deltaBuf += text
-      this.deltaTimer ??= setTimeout(() => {
-        this.deltaTimer = null
-        flushDelta()
-      }, 50)
-    }
-
-    // 通知订阅(审批请求处理器已在 startClient 挂接,此处只处理回合通知)
-    const unsub = client.onNotification((method, params) => {
-      const p = (params ?? {}) as Record<string, unknown>
-      lastActivity = Date.now()
-      if (method === 'item/agentMessage/delta') {
-        const delta = typeof p.delta === 'string' ? p.delta : ''
-        if (delta) {
-          this.turnActive = true
-          pushDelta(delta)
-        }
-        return
-      }
-      if (method === 'turn/started') {
-        const turn = p.turn as Record<string, unknown> | undefined
-        this.turnId = typeof turn?.id === 'string' ? turn.id : this.turnId
-        this.turnActive = true
-        enqueue({ kind: 'status', status: { state: 'WORKING', timestamp: new Date().toISOString() } })
-        return
-      }
-      if (method === 'item/started') {
-        const item = p.item as Record<string, unknown> | undefined
-        const t = String(item?.type ?? '')
-        if (['commandExecution', 'mcpToolCall', 'fileChange', 'dynamicToolCall', 'webSearch', 'collabToolCall'].includes(t)) {
-          const label = t === 'commandExecution'
-            ? String(item?.command ?? 'command')
-            : String(item?.tool ?? item?.title ?? t)
-          enqueue({
-            kind: 'status',
-            status: {
-              state: 'WORKING',
-              message: {
-                messageId: randomUUID(),
-                contextId: this.channelId,
-                role: 'ROLE_AGENT',
-                parts: [{ text: `🔧 ${label}${toolArgsPreview(item?.input ?? item?.arguments ?? item?.command)}` }],
-              },
-              timestamp: new Date().toISOString(),
-            },
-          })
-        }
-        if (t === 'contextCompaction') this.compacting = true
-        return
-      }
-      if (method === 'item/completed') {
-        const item = p.item as Record<string, unknown> | undefined
-        if (String(item?.type ?? '') === 'agentMessage' && typeof item?.text === 'string') {
-          agentText += item.text
-        }
-        if (String(item?.type ?? '') === 'contextCompaction') this.compacting = false
-        return
-      }
-      if (method === 'thread/tokenUsage/updated') {
-        const usage = (p.usage ?? p.tokenUsage ?? p) as Record<string, unknown>
-        const input = Number(usage.input_tokens ?? usage.inputTokens ?? usage.total_tokens ?? usage.totalTokens)
-        if (Number.isFinite(input) && input > 0) this.lastUsage = { input, at: Date.now() }
-        return
-      }
-      if (method === 'turn/completed') {
-        const turn = (p.turn ?? {}) as Record<string, unknown>
-        const status = String(turn.status ?? 'completed')
-        if (status === 'failed') {
-          const err = (turn.error ?? {}) as Record<string, unknown>
-          const info = String(err.codexErrorInfo ?? '')
-          enqueue({
-            kind: 'error',
-            error: {
-              code: info ? `CODEX_${info}` : 'CODEX_LLM_ERROR',
-              message: String(err.message ?? 'codex 回合失败'),
-            },
-          })
-        }
-        else {
-          // completed / interrupted:中断按 done 收口(消息按已处理落账)
-          enqueue({ kind: 'done', final: taskId ? { taskId } : undefined })
-        }
-        return
-      }
-      if (method === 'error') {
-        enqueue({
-          kind: 'error',
-          error: { code: 'CODEX_ERROR', message: String(p.message ?? p.error ?? JSON.stringify(params).slice(0, 300)) },
-        })
-      }
-    })
-
-    // abort 传导
-    const onAbort = (): void => {
-      log.warn(`[CodexAgent:${this.selfAgentId}] run 被 abort → turn/interrupt,taskId=${taskId ?? '-'}`)
-      void client.request('turn/interrupt', { threadId: this.threadId, ...(this.turnId ? { turnId: this.turnId } : {}) }, 15_000).catch(() => {})
-      setTimeout(() => {
-        if (!isDone) enqueue({ kind: 'done', final: taskId ? { taskId } : undefined })
-      }, 5000)
-    }
-    if (signal?.aborted) onAbort()
-    else signal?.addEventListener('abort', onAbort, { once: true })
-
-    // 投递 turn
-    try {
-      await client.request('turn/start', {
-        threadId: this.threadId,
-        input: [{ type: 'text', text: prompt }],
-      }, 60_000)
-    }
-    catch (err) {
-      unsub()
-      signal?.removeEventListener('abort', onAbort)
-      this.turnActive = false
-      yield {
-        kind: 'error',
-        error: {
-          code: 'CODEX_PROMPT_FAILED',
-          message: `codex turn/start 失败: ${err instanceof Error ? err.message : String(err)}`,
-        },
-      }
-      return
-    }
-
-    try {
-      while (!isDone || queue.length > 0) {
-        if (queue.length === 0 && !isDone) {
-          const remaining = timeoutMs - (Date.now() - lastActivity)
-          if (remaining <= 0) {
-            void client.request('turn/interrupt', { threadId: this.threadId }, 15_000).catch(() => {})
-            enqueue({
-              kind: 'error',
-              error: { code: 'CODEX_TURN_STALLED', message: `回合停滞 ${Math.round(timeoutMs / 1000)}s 无事件,已中止` },
-            })
-            continue
-          }
-          await new Promise<void>((r) => {
-            resolveWait = r
-            setTimeout(() => {
-              resolveWait = null
-              r()
-            }, remaining + 100)
-          })
-        }
-        while (queue.length > 0) {
-          yield queue.shift()!
-        }
-      }
-    }
-    finally {
-      flushDelta()
-      unsub()
-      signal?.removeEventListener('abort', onAbort)
-      this.turnActive = false
-      this.turnId = null
-    }
-  }
-
-  /** supervise 用:收齐整个回合的事件流(supervise 决策解析在调用方) */
-  private async collectTurn(prompt: string, timeoutMs: number, signal?: AbortSignal): Promise<AgentEvent[]> {
-    const events: AgentEvent[] = []
-    for await (const e of this.streamTurn(prompt, undefined, timeoutMs, signal)) {
-      events.push(e)
-      if (e.kind === 'error') break
-    }
-    return events
-  }
-
-  // ===== HITL 登记 =====
-
-  private registerApprovalHitl(rpcId: string | number, itemId: string, kindLabel: 'command' | 'file', p: Record<string, unknown>): void {
-    const id = `codex-${itemId}`
-    if (this.pendingApprovals.has(id)) return
-    const title = kindLabel === 'command'
-      ? `codex 命令审批:${String(p.command ?? '(未知命令)').slice(0, 200)}`
-      : `codex 文件变更审批:${String(p.cwd ?? p.grantRoot ?? '')}`
-    const registry = getHitlRegistry()
-    registry.register({
-      kind: 'codex-approval',
-      id,
-      agentId: this.selfAgentId,
-      agentName: this.agentName,
-      channelId: this.channelId,
-      pid: this.client?.pid,
-      method: 'confirm',
-      title,
-      detail: typeof p.reason === 'string' ? p.reason : undefined,
-      createdAt: new Date().toISOString(),
-      expiresAt: null,
-    })
-    const timeoutMs = harnessSettings().hitl_timeout_ms
-    const timer = timeoutMs > 0
-      ? setTimeout(() => {
-          void this.respondHitl('codex-approval', id, { cancelled: true }).catch(() => {})
-          registry.resolve('codex-approval', id, 'expired')
-        }, timeoutMs)
-      : null
-    this.pendingApprovals.set(id, { rpcId, timer })
-  }
-
-  private registerUserInputHitl(rpcId: string | number, p: Record<string, unknown>): void {
-    const id = `codex-input-${randomUUID().slice(0, 8)}`
-    const questions = Array.isArray(p.questions) ? p.questions : []
-    const first = (questions[0] ?? {}) as Record<string, unknown>
-    const registry = getHitlRegistry()
-    registry.register({
-      kind: 'codex-approval',
-      id,
-      agentId: this.selfAgentId,
-      agentName: this.agentName,
-      channelId: this.channelId,
-      pid: this.client?.pid,
-      method: 'input',
-      title: String(first.question ?? first.header ?? 'codex 提问'),
-      detail: typeof p.reason === 'string' ? p.reason : undefined,
-      createdAt: new Date().toISOString(),
-      expiresAt: null,
-    })
-    const timeoutMs = harnessSettings().hitl_timeout_ms
-    const timer = timeoutMs > 0
-      ? setTimeout(() => {
-          void this.respondUserInput(rpcId, id, { cancelled: true }).catch(() => {})
-        }, timeoutMs)
-      : null
-    this.pendingApprovals.set(id, { rpcId, timer })
-  }
-
-  private async respondUserInput(rpcId: string | number, id: string, outcome: { cancelled?: boolean, value?: string }): Promise<void> {
-    const pending = this.pendingApprovals.get(id)
-    if (!pending) return
-    const client = this.client
-    if (!client) return
-    if (outcome.cancelled) {
-      client.respondError(rpcId, -32800, '人工取消')
-      getHitlRegistry().resolve('codex-approval', id, 'cancelled')
-    }
-    else {
-      client.respond(rpcId, { answers: [{ answer: outcome.value ?? '' }] })
-      getHitlRegistry().resolve('codex-approval', id, 'answered')
-    }
-    if (pending.timer) clearTimeout(pending.timer)
-    this.pendingApprovals.delete(id)
-  }
-
-  // ===== 客户端管理 =====
-
-  private 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
-  }
-
-  private 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
-   * 配置,自定义网关/密钥不丢失);全新目录 → 独立写入。
-   */
-  private writeCodexHomeConfig(): void {
-    let home = this.config.codexHome
-    if (!home && this.config.effort) {
-      // effort 需要配置文件面(model_reasoning_effort):自动种子化 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 { /* 单文件缺失忽略 */ }
-      }
-    }
-    if (!home) return
-    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)
-    }
-  }
-}
+/**
+ * CodexAgentImpl — OpenAI Codex CLI(app-server)harness 的 AgentInterface 实现。
+ *
+ * 进程模型:每 Agent 一个 `codex app-server` 子进程(stdio NDJSON JSON-RPC v2,
+ * lazy spawn 跨消息复用);thread/start 建会话,turn/start 驱动回合。
+ *
+ *  - prompt/工具面与 omp 全引擎同源(prompt-builder / host-tool-bridge);
+ *    工具经 stdio MCP 桥注入(config.toml 由 impl 装配 [mcp_servers.aw])
+ *  - 事件映射:item/agentMessage/delta → delta;item/started → 🔧 status;
+ *    turn/completed → artifact + done / error(codexErrorInfo 结构化)
+ *  - HITL:item/commandExecution|fileChange/requestApproval(server→client 请求)
+ *    → hitl-registry 登记 → respondHitl 应答(decision: accept/decline/cancel)
+ *  - steer:turn 运行中 → turn/steer;无 active turn → 'deferred'
+ *  - 上下文治理:thread/tokenUsage/updated 被动跟踪;越阈值 → thread/compact/start
+ *
+ * 协议权威:github.com/openai/codex codex-rs/app-server/README.md(v0.149 实测)。
+ */
+import { createLogger } from '../logger'
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import { mkdirSync, writeFileSync, existsSync, readFileSync, copyFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import type { AgentEvent, AgentInterface, AgentInfo, AgentRunContext, AgentRunRequest } from './agent-interface'
+import type { AgentContextStats } from '../types/task'
+import { registerHarnessProcess, bindHarnessProcess, markHarnessProcessExit, killHarnessProcess } from './harness-process'
+import { peerPrompt, systemManual, toolArgsPreview, workerPrompt } from './prompt-builder'
+import { getHitlRegistry } from './hitl-registry'
+import { harnessSettings } from '../settings'
+import { StdioJsonRpcClient } from './adapters/stdio-jsonrpc'
+import { BaseAgentImpl } from './base-agent'
+import { generateMcpBridgeEnv } from './harness-env'
+
+const log = createLogger('workshop.codex')
+
+export interface CodexAgentConfig {
+  /** codex 可执行文件(默认取 harness.codex_command 设置) */
+  command?: string
+  /** 额外 CLI 参数(app-server 之前) */
+  args?: string[]
+  cwd?: string
+  /** 模型(如 gpt-5.2) */
+  model?: string
+  /** 审批策略(默认 on-request:沙箱内自由,越界请求审批 → HITL) */
+  approvalPolicy?: 'untrusted' | 'on-request' | 'never'
+  /** 沙箱(默认 workspace-write) */
+  sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access'
+  /** CODEX_HOME(缺省进程环境;配置隔离/多账户时按 agent 指定;effort 未指定 home 时自动种子化) */
+  codexHome?: string
+  /** 思考 effort(model_reasoning_effort;需 CODEX_HOME 配置面,未指定 home 时自动种子化) */
+  effort?: string
+  /** 上下文窗口(usage 百分比计算) */
+  contextWindow?: number
+  /** 压缩阈值(0-1,默认 0.7) */
+  compactThreshold?: number
+  promptTimeoutMs?: number
+  superviseTimeoutMs?: number
+  systemPromptPrefix?: string
+  scenarioPrompt?: string
+  agentId?: string
+  name?: string
+  role?: 'lead' | 'worker'
+  channelId?: string
+  token?: string
+  baseUrl?: string
+  mcpBridgePath?: string
+}
+
+export class CodexAgentImpl extends BaseAgentImpl implements AgentInterface {
+  private readonly config: CodexAgentConfig
+  private agentInfo: AgentInfo | null = null
+  private readonly bridgeCtx = {
+    identity: { agentId: '', channelId: '', role: 'worker' as 'lead' | 'worker', name: 'agent' },
+    state: this.toolState,
+    getWorkspace: () => this.workspace,
+  }
+
+  private agentRole: 'lead' | 'worker' = 'worker'
+
+  private client: StdioJsonRpcClient | null = null
+  private clientStarting: Promise<void> | null = null
+  private threadId: string | null = null
+  private turnId: string | null = null
+
+  // 回合状态
+  private turnActive = false
+  private deltaBuf = ''
+  private deltaTimer: ReturnType<typeof setTimeout> | null = null
+  private lastUsage: { input: number, at: number } | null = null
+  private compacting = false
+  private lastCompactAt = 0
+  /** 待应答审批(approval request id → JSON-RPC id) */
+  private pendingApprovals = new Map<string, { rpcId: string | number, timer: ReturnType<typeof setTimeout> | null }>()
+
+  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(): Record<string, unknown> {
+    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,
+    }
+  }
+
+  /** 实时注入:turn 运行中 → turn/steer;否则 'deferred'(消息保持 pending) */
+  async steer(text: string): Promise<'steer' | 'deferred'> {
+    const client = this.client
+    if (!client?.alive || !this.threadId || !this.turnActive) return 'deferred'
+    try {
+      await client.request('turn/steer', {
+        threadId: this.threadId,
+        input: [{ type: 'text', text }],
+      }, 15_000)
+      return 'steer'
+    }
+    catch {
+      // 无 active turn / 引擎拒绝 → 消息保持 pending 由消费循环处理
+      return 'deferred'
+    }
+  }
+
+  /** HITL 应答:审批请求 → JSON-RPC 应答(decision) */
+  async respondHitl(kind: string, id: string, outcome: {
+    confirmed?: boolean
+    cancelled?: boolean
+    value?: string
+    response?: string
+    comment?: string
+  }): Promise<void> {
+    if (kind !== 'codex-approval') return
+    const pending = this.pendingApprovals.get(id)
+    if (!pending) throw new Error(`待办不存在或已处理: ${id}`)
+    const client = this.client
+    if (!client) throw new Error('codex 会话已关闭')
+    const decision = outcome.cancelled === true
+      ? 'cancel'
+      : outcome.confirmed === true ? 'accept' : 'decline'
+    client.respond(pending.rpcId, { decision })
+    if (pending.timer) clearTimeout(pending.timer)
+    this.pendingApprovals.delete(id)
+    getHitlRegistry().resolve(kind, id, decision === 'cancel' ? 'cancelled' : 'answered')
+  }
+
+  /** 上下文治理(post-settle):越阈值 → thread/compact/start */
+  async onTurnSettled(): Promise<void> {
+    const client = this.client
+    if (!client?.alive || !this.threadId || this.compacting) return
+    const stats = this.getContextStats()
+    const threshold = this.config.compactThreshold ?? 0.7
+    if (!stats?.percent || stats.percent < threshold) return
+    if (Date.now() - this.lastCompactAt < 5 * 60_000) return
+    this.compacting = true
+    this.lastCompactAt = Date.now()
+    try {
+      await client.request('thread/compact/start', { threadId: this.threadId }, 30_000)
+      log.info(`[CodexAgent:${this.selfAgentId}] 上下文压缩已触发(percent=${(stats.percent * 100).toFixed(0)}%)`)
+    }
+    catch (err) {
+      log.warn(`[CodexAgent:${this.selfAgentId}] compact 发起失败(放行):`, err instanceof Error ? err.message : err)
+    }
+    finally {
+      this.compacting = false
+    }
+  }
+
+  protected async* workerTurn(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
+    const taskId = request.taskId ?? (request.message.metadata?.['x-aw-task-id'] as string | undefined)
+    if (!taskId) return
+    this.toolState.currentTaskId = taskId
+    try {
+      await this.ensureClient(ctx)
+      const taskText = request.message.parts.map((p) => {
+        if ('text' in p) return p.text
+        if ('data' in p) return JSON.stringify(p.data)
+        if ('url' in p) return p.url
+        if ('raw' in p) return p.raw
+        return ''
+      }).join('\n')
+      const prompt = workerPrompt({
+        agentName: this.agentName,
+        channelId: this.channelId,
+        taskId,
+        taskText,
+        memory: request.memory,
+        ctxPrefix: await this.contextPrefix(),
+        manual: systemManual(),
+      })
+      yield* this.streamTurn(prompt, taskId, this.config.promptTimeoutMs ?? 600_000, ctx.signal)
+    }
+    finally {
+      this.toolState.currentTaskId = null
+    }
+  }
+
+  protected async* peerTurn(request: AgentRunRequest, ctx: AgentRunContext): AsyncGenerator<AgentEvent, void, unknown> {
+    await this.ensureClient(ctx)
+    const msg = request.message
+    const fromId = request.fromAgentId
+      ?? (typeof msg.metadata?.['x-aw-from-label'] === 'string' ? msg.metadata['x-aw-from-label'] : undefined)
+      ?? 'unknown'
+    const requireReply = msg.metadata?.['x-aw-require-reply'] === 'true'
+    const crossChannel = msg.metadata?.['x-aw-cross-channel'] === 'true'
+    this.toolState.replyContext = requireReply && request.fromAgentId && !crossChannel
+      ? { fromId: request.fromAgentId, messageId: msg.messageId }
+      : null
+    const msgText = msg.parts.map((p) => {
+      if ('text' in p) return p.text
+      if ('data' in p) return JSON.stringify(p.data)
+      if ('url' in p) return p.url
+      if ('raw' in p) return p.raw
+      return ''
+    }).join('\n')
+    const prompt = peerPrompt({
+      agentName: this.agentName,
+      role: this.agentRole,
+      channelId: this.channelId,
+      ctxPrefix: await this.contextPrefix(),
+      manual: systemManual(),
+      memory: request.memory,
+      fromId,
+      messageId: msg.messageId,
+      requireReply,
+      isReply: typeof msg.metadata?.['x-aw-in-reply-to'] === 'string',
+      crossChannel,
+      fromChannel: typeof msg.metadata?.['x-aw-from-channel'] === 'string' ? String(msg.metadata['x-aw-from-channel']) : '',
+      msgText,
+    })
+    yield* this.streamTurn(prompt, undefined, this.config.promptTimeoutMs ?? 600_000, ctx.signal)
+  }
+
+  // ===== 回合执行 =====
+
+  /**
+   * 流式回合:turn/start → 逐事件产出(delta/status)→ turn/completed 收口。
+   * artifact 在 done 前注入(item/completed agentMessage 聚合文本)。
+   */
+  private async* streamTurn(prompt: string, taskId: string | undefined, timeoutMs: number, signal?: AbortSignal): AsyncGenerator<AgentEvent, void, unknown> {
+    const client = this.client
+    if (!client || !this.threadId) {
+      yield { kind: 'error', error: { code: 'CODEX_NOT_READY', message: 'codex 会话未就绪' } }
+      return
+    }
+    const queue: AgentEvent[] = []
+    let isDone = false
+    let resolveWait: (() => void) | null = null
+    let lastActivity = Date.now()
+    let agentText = ''
+    this.turnActive = true
+    this.turnId = null
+
+    const enqueue = (e: AgentEvent): void => {
+      if (e.kind === 'done' && !isDone) {
+        if (agentText.trim()) {
+          queue.push({
+            kind: 'artifact',
+            artifact: { artifactId: randomUUID(), name: 'output', parts: [{ text: agentText.trim() }] },
+            lastChunk: true,
+            totalChunks: 1,
+          })
+        }
+        this.turnActive = false
+      }
+      if (e.kind === 'done' || e.kind === 'error') {
+        isDone = true
+        this.turnActive = false
+        flushDelta()
+      }
+      queue.push(e)
+      lastActivity = Date.now()
+      resolveWait?.()
+      resolveWait = null
+    }
+
+    const flushDelta = (): void => {
+      if (this.deltaTimer) {
+        clearTimeout(this.deltaTimer)
+        this.deltaTimer = null
+      }
+      if (!this.deltaBuf) return
+      const text = this.deltaBuf
+      this.deltaBuf = ''
+      queue.push({ kind: 'delta', delta: { text } })
+    }
+    const pushDelta = (text: string): void => {
+      this.deltaBuf += text
+      this.deltaTimer ??= setTimeout(() => {
+        this.deltaTimer = null
+        flushDelta()
+      }, 50)
+    }
+
+    // 通知订阅(审批请求处理器已在 startClient 挂接,此处只处理回合通知)
+    const unsub = client.onNotification((method, params) => {
+      const p = (params ?? {}) as Record<string, unknown>
+      lastActivity = Date.now()
+      if (method === 'item/agentMessage/delta') {
+        const delta = typeof p.delta === 'string' ? p.delta : ''
+        if (delta) {
+          this.turnActive = true
+          pushDelta(delta)
+        }
+        return
+      }
+      if (method === 'turn/started') {
+        const turn = p.turn as Record<string, unknown> | undefined
+        this.turnId = typeof turn?.id === 'string' ? turn.id : this.turnId
+        this.turnActive = true
+        enqueue({ kind: 'status', status: { state: 'WORKING', timestamp: new Date().toISOString() } })
+        return
+      }
+      if (method === 'item/started') {
+        const item = p.item as Record<string, unknown> | undefined
+        const t = String(item?.type ?? '')
+        if (['commandExecution', 'mcpToolCall', 'fileChange', 'dynamicToolCall', 'webSearch', 'collabToolCall'].includes(t)) {
+          const label = t === 'commandExecution'
+            ? String(item?.command ?? 'command')
+            : String(item?.tool ?? item?.title ?? t)
+          enqueue({
+            kind: 'status',
+            status: {
+              state: 'WORKING',
+              message: {
+                messageId: randomUUID(),
+                contextId: this.channelId,
+                role: 'ROLE_AGENT',
+                parts: [{ text: `🔧 ${label}${toolArgsPreview(item?.input ?? item?.arguments ?? item?.command)}` }],
+              },
+              timestamp: new Date().toISOString(),
+            },
+          })
+        }
+        if (t === 'contextCompaction') this.compacting = true
+        return
+      }
+      if (method === 'item/completed') {
+        const item = p.item as Record<string, unknown> | undefined
+        if (String(item?.type ?? '') === 'agentMessage' && typeof item?.text === 'string') {
+          agentText += item.text
+        }
+        if (String(item?.type ?? '') === 'contextCompaction') this.compacting = false
+        return
+      }
+      if (method === 'thread/tokenUsage/updated') {
+        const usage = (p.usage ?? p.tokenUsage ?? p) as Record<string, unknown>
+        const input = Number(usage.input_tokens ?? usage.inputTokens ?? usage.total_tokens ?? usage.totalTokens)
+        if (Number.isFinite(input) && input > 0) this.lastUsage = { input, at: Date.now() }
+        return
+      }
+      if (method === 'turn/completed') {
+        const turn = (p.turn ?? {}) as Record<string, unknown>
+        const status = String(turn.status ?? 'completed')
+        if (status === 'failed') {
+          const err = (turn.error ?? {}) as Record<string, unknown>
+          const info = String(err.codexErrorInfo ?? '')
+          enqueue({
+            kind: 'error',
+            error: {
+              code: info ? `CODEX_${info}` : 'CODEX_LLM_ERROR',
+              message: String(err.message ?? 'codex 回合失败'),
+            },
+          })
+        }
+        else {
+          // completed / interrupted:中断按 done 收口(消息按已处理落账)
+          enqueue({ kind: 'done', final: taskId ? { taskId } : undefined })
+        }
+        return
+      }
+      if (method === 'error') {
+        enqueue({
+          kind: 'error',
+          error: { code: 'CODEX_ERROR', message: String(p.message ?? p.error ?? JSON.stringify(params).slice(0, 300)) },
+        })
+      }
+    })
+
+    // abort 传导
+    const onAbort = (): void => {
+      log.warn(`[CodexAgent:${this.selfAgentId}] run 被 abort → turn/interrupt,taskId=${taskId ?? '-'}`)
+      void client.request('turn/interrupt', { threadId: this.threadId, ...(this.turnId ? { turnId: this.turnId } : {}) }, 15_000).catch(() => {})
+      setTimeout(() => {
+        if (!isDone) enqueue({ kind: 'done', final: taskId ? { taskId } : undefined })
+      }, 5000)
+    }
+    if (signal?.aborted) onAbort()
+    else signal?.addEventListener('abort', onAbort, { once: true })
+
+    // 投递 turn
+    try {
+      await client.request('turn/start', {
+        threadId: this.threadId,
+        input: [{ type: 'text', text: prompt }],
+      }, 60_000)
+    }
+    catch (err) {
+      unsub()
+      signal?.removeEventListener('abort', onAbort)
+      this.turnActive = false
+      yield {
+        kind: 'error',
+        error: {
+          code: 'CODEX_PROMPT_FAILED',
+          message: `codex turn/start 失败: ${err instanceof Error ? err.message : String(err)}`,
+        },
+      }
+      return
+    }
+
+    try {
+      while (!isDone || queue.length > 0) {
+        if (queue.length === 0 && !isDone) {
+          const remaining = timeoutMs - (Date.now() - lastActivity)
+          if (remaining <= 0) {
+            void client.request('turn/interrupt', { threadId: this.threadId }, 15_000).catch(() => {})
+            enqueue({
+              kind: 'error',
+              error: { code: 'CODEX_TURN_STALLED', message: `回合停滞 ${Math.round(timeoutMs / 1000)}s 无事件,已中止` },
+            })
+            continue
+          }
+          await new Promise<void>((r) => {
+            resolveWait = r
+            setTimeout(() => {
+              resolveWait = null
+              r()
+            }, remaining + 100)
+          })
+        }
+        while (queue.length > 0) {
+          yield queue.shift()!
+        }
+      }
+    }
+    finally {
+      flushDelta()
+      unsub()
+      signal?.removeEventListener('abort', onAbort)
+      this.turnActive = false
+      this.turnId = null
+    }
+  }
+
+  /** supervise 用:收齐整个回合的事件流(supervise 决策解析在调用方) */
+  protected async collectTurnEvents(prompt: string, timeoutMs: number, signal?: AbortSignal): Promise<AgentEvent[]> {
+    const events: AgentEvent[] = []
+    for await (const e of this.streamTurn(prompt, undefined, timeoutMs, signal)) {
+      events.push(e)
+      if (e.kind === 'error') break
+    }
+    return events
+  }
+
+  // ===== HITL 登记 =====
+
+  private registerApprovalHitl(rpcId: string | number, itemId: string, kindLabel: 'command' | 'file', p: Record<string, unknown>): void {
+    const id = `codex-${itemId}`
+    if (this.pendingApprovals.has(id)) return
+    const title = kindLabel === 'command'
+      ? `codex 命令审批:${String(p.command ?? '(未知命令)').slice(0, 200)}`
+      : `codex 文件变更审批:${String(p.cwd ?? p.grantRoot ?? '')}`
+    const registry = getHitlRegistry()
+    registry.register({
+      kind: 'codex-approval',
+      id,
+      agentId: this.selfAgentId,
+      agentName: this.agentName,
+      channelId: this.channelId,
+      pid: this.client?.pid,
+      method: 'confirm',
+      title,
+      detail: typeof p.reason === 'string' ? p.reason : undefined,
+      createdAt: new Date().toISOString(),
+      expiresAt: null,
+    })
+    const timeoutMs = harnessSettings().hitl_timeout_ms
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          void this.respondHitl('codex-approval', id, { cancelled: true }).catch(() => {})
+          registry.resolve('codex-approval', id, 'expired')
+        }, timeoutMs)
+      : null
+    this.pendingApprovals.set(id, { rpcId, timer })
+  }
+
+  private registerUserInputHitl(rpcId: string | number, p: Record<string, unknown>): void {
+    const id = `codex-input-${randomUUID().slice(0, 8)}`
+    const questions = Array.isArray(p.questions) ? p.questions : []
+    const first = (questions[0] ?? {}) as Record<string, unknown>
+    const registry = getHitlRegistry()
+    registry.register({
+      kind: 'codex-approval',
+      id,
+      agentId: this.selfAgentId,
+      agentName: this.agentName,
+      channelId: this.channelId,
+      pid: this.client?.pid,
+      method: 'input',
+      title: String(first.question ?? first.header ?? 'codex 提问'),
+      detail: typeof p.reason === 'string' ? p.reason : undefined,
+      createdAt: new Date().toISOString(),
+      expiresAt: null,
+    })
+    const timeoutMs = harnessSettings().hitl_timeout_ms
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          void this.respondUserInput(rpcId, id, { cancelled: true }).catch(() => {})
+        }, timeoutMs)
+      : null
+    this.pendingApprovals.set(id, { rpcId, timer })
+  }
+
+  private async respondUserInput(rpcId: string | number, id: string, outcome: { cancelled?: boolean, value?: string }): Promise<void> {
+    const pending = this.pendingApprovals.get(id)
+    if (!pending) return
+    const client = this.client
+    if (!client) return
+    if (outcome.cancelled) {
+      client.respondError(rpcId, -32800, '人工取消')
+      getHitlRegistry().resolve('codex-approval', id, 'cancelled')
+    }
+    else {
+      client.respond(rpcId, { answers: [{ answer: outcome.value ?? '' }] })
+      getHitlRegistry().resolve('codex-approval', id, 'answered')
+    }
+    if (pending.timer) clearTimeout(pending.timer)
+    this.pendingApprovals.delete(id)
+  }
+
+  // ===== 客户端管理 =====
+
+  private 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
+  }
+
+  private 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
+   * 配置,自定义网关/密钥不丢失);全新目录 → 独立写入。
+   */
+  private writeCodexHomeConfig(): void {
+    let home = this.config.codexHome
+    if (!home && this.config.effort) {
+      // effort 需要配置文件面(model_reasoning_effort):自动种子化 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 { /* 单文件缺失忽略 */ }
+      }
+    }
+    if (!home) return
+    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)
+    }
+  }
+}