agentworkshop 0.7.70 → 0.8.0

package/server/api/workshop/process-model/experiments.ts

@@ -0,0 +1,43 @@
+/**
+ * GET /api/workshop/process-model/experiments?lineId= —— 模拟参数试验计划列表(非 admin 必须带 lineId)
+ * POST —— 创建计划(仅 simulated 产线;真实线 SIM_ONLY_VIOLATION;创建入册 D16/SW1.6)
+ */
+import { getQuery, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { filterByLine } from '@/server/services/workshop/permissions'
+import { createExperimentPlan, listExperimentPlans } from '@/server/services/workshop/process-model/experiment'
+import { assertOptimizationAccess, recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const method = event.method?.toUpperCase() ?? 'GET'
+  if (method === 'GET') {
+    const q = getQuery(event)
+    const lineId = typeof q.lineId === 'string' ? q.lineId : undefined
+    if (lineId) assertOptimizationAccess(user, 'read', { kind: 'experiment', lineId })
+    const rows = listExperimentPlans(lineId)
+    // 无 lineId 时(admin 全量)仍按产线可见性过滤;非 admin 不带 lineId 只能看到自己有权看的产线
+    return { plans: user.role === 'admin' ? rows : filterByLine(user, rows, (r: { lineId?: string }) => r.lineId) }
+  }
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const lineId = String(body.lineId ?? '')
+  if (!lineId) throw createError({ statusCode: 400, statusMessage: 'lineId required' })
+  assertOptimizationAccess(user, 'write', { kind: 'experiment', lineId })
+  const plan = createExperimentPlan({
+    lineId,
+    specId: typeof body.specId === 'string' ? body.specId : undefined,
+    levels: (body.levels ?? {}) as Record<string, number[]>,
+    repeats: typeof body.repeats === 'number' ? body.repeats : undefined,
+    settleMs: typeof body.settleMs === 'number' ? body.settleMs : undefined,
+    observeMs: typeof body.observeMs === 'number' ? body.observeMs : undefined,
+    randomizedOrder: body.randomizedOrder !== false,
+    abortOnAlarm: body.abortOnAlarm !== false,
+    budget: body.budget as { maxRuns?: number, maxDurationMs?: number } | undefined,
+    createdBy: user.id,
+  })
+  const planDetail = JSON.parse(plan.planJson || '{}') as { repeats?: number, specId?: string | null }
+  recordConfigAction(user, 'process_model.experiment.create', { kind: 'process_model_experiment', id: plan.id },
+    `创建模拟试验计划 ${plan.id}(line=${lineId},repeats=${planDetail.repeats ?? '?'})`, { lineId, specId: planDetail.specId ?? undefined }, lineId)
+  return { plan }
+})

package/server/api/workshop/process-model/specs/[id]/publish.post.ts

@@ -0,0 +1,22 @@
+/**
+ * POST /api/workshop/process-model/specs/:id/publish?version= —— 发布(不可变)。
+ * 归属:产线可见性(readonly grant);拒绝走统一审计(D16)。
+ */
+import { getQuery, getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { getProcessModelSpecRepo, parseSpecRow } from '@/server/services/workshop/process-model/spec.repo'
+import { assertOptimizationAccess, recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const id = getRouterParam(event, 'id') ?? ''
+  const q = getQuery(event)
+  const row = getProcessModelSpecRepo().get(id, typeof q.version === 'string' ? Number(q.version) : undefined)
+  if (!row) throw createError({ statusCode: 404, statusMessage: `ProcessModelSpec ${id} 不存在` })
+  assertOptimizationAccess(user, 'publish', { kind: 'spec', id, version: row.version })
+  const published = getProcessModelSpecRepo().publish(id, row.version)
+  recordConfigAction(user, 'process_model.spec.publish', { kind: 'process_model_spec', id: `${id}@${published.version}` },
+    `发布 ProcessModelSpec ${id}@${published.version}`, { lineId: row.lineId, contentHash: row.contentHash }, row.lineId)
+  return { spec: published, parsed: parseSpecRow(published), by: user.id }
+})

package/server/api/workshop/process-model/specs/index.ts

@@ -0,0 +1,34 @@
+/**
+ * GET /api/workshop/process-model/specs —— ProcessModelSpec 列表(产线可见性过滤)。
+ * POST —— 校验并登记 draft(不改已发布版本;修改 = 新版本)。
+ */
+import { readBody, getQuery } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { filterByLine, requireLineMode } from '@/server/services/workshop/permissions'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+import { parseProcessModelSpec } from '@/server/services/workshop/process-model/spec'
+import { getProcessModelSpecRepo, parseSpecRow } from '@/server/services/workshop/process-model/spec.repo'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const method = event.method?.toUpperCase() ?? 'GET'
+  if (method === 'GET') {
+    const q = getQuery(event)
+    const lineId = typeof q.lineId === 'string' ? q.lineId : undefined
+    const rows = getProcessModelSpecRepo().list({ lineId, status: typeof q.status === 'string' ? q.status : undefined, limit: 200 })
+    const visible = filterByLine(user, rows, r => r.lineId)
+    return { specs: visible.map(r => ({ ...r, spec: parseSpecRow(r) })) }
+  }
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const spec = parseProcessModelSpec(body)
+  requireLineMode(user, spec.lineId, 'readonly')
+  const row = getProcessModelSpecRepo().insert(spec, { ownerUserId: user.id })
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'process_model.spec.create', kind: 'system',
+    summary: `登记 ProcessModelSpec ${spec.id}@${spec.version}(trainer=${spec.trainer.ref})`,
+    targetKind: 'process_model_spec', targetId: `${spec.id}@${spec.version}`, lineId: spec.lineId,
+  })
+  return { spec: row }
+})

package/server/api/workshop/process-model/train.post.ts

@@ -0,0 +1,36 @@
+/**
+ * POST /api/workshop/process-model/train —— 内置训练器作业(配置驱动,无需用户代码)。
+ * body: { spec, datasetId, modelName?, modelDescription? }
+ * 权限:editor/admin 角色 + 产线可见性(readonly)+ 训练提交入册(D16/SW1.6;viewer 不可提交算力作业)。
+ */
+import { readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { parseProcessModelSpec } from '@/server/services/workshop/process-model/spec'
+import { submitJob } from '@/server/services/workshop/aml/job-orchestrator'
+import { assertOptimizationAccess, recordConfigAction } from '@/server/services/workshop/optimization/access'
+import { AppError } from '@/server/utils/errors'
+
+export default defineApiHandler(async (event) => {
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const spec = parseProcessModelSpec(body.spec)
+  const datasetId = String(body.datasetId ?? '')
+  if (!datasetId) throw new AppError(422, 'DATASET_REQUIRED', 'datasetId 必填(先构建 manifest v2 数据集)')
+  assertOptimizationAccess(user, 'write', { kind: 'train', lineId: spec.lineId })
+  assertOptimizationAccess(user, 'read', { kind: 'dataset', id: datasetId })
+  const job = submitJob({
+    datasetId,
+    purpose: spec.purpose,
+    trainerRef: spec.trainer.ref,
+    processModelSpec: spec as unknown as Record<string, unknown>,
+    modelName: typeof body.modelName === 'string' ? body.modelName : `${spec.id}@${spec.version}`,
+    modelDescription: typeof body.modelDescription === 'string' ? body.modelDescription : `ProcessModelSpec ${spec.id}@${spec.version}(${spec.trainer.ref})`,
+    agent: { id: user.id },
+    byKind: 'user',
+  })
+  recordConfigAction(user, 'process_model.train.submit', { kind: 'aml_job', id: job.id },
+    `提交训练作业 ${job.id}(spec=${spec.id}@${spec.version},trainer=${spec.trainer.ref})`,
+    { datasetId, trainerRef: spec.trainer.ref }, spec.lineId)
+  return { job }
+})

package/server/harness/aw-mcp-bridge.mjs

@@ -18,6 +18,7 @@
  * 子进程拉起,不得假设仓库 node_modules 的解析路径。
  */
 import { createInterface } from 'node:readline'
+import { toolSignature as bridgeSignature } from './aw-mcp-signature.mjs'
 
 const BASE_URL = (process.env.AW_BASE_URL ?? 'http://127.0.0.1:3000').replace(/\/$/, '')
 const AGENT_ID = process.env.AW_AGENT_ID ?? ''
@@ -34,21 +35,39 @@ if (!AGENT_ID || !AGENT_TOKEN) {
 let toolCache = { at: 0, tools: [] }
 let clientReady = false
 let lastToolSignature = ''
+/** WP6:最近一次成功响应的 ETag(带 If-None-Match 轮询,无变更时服务端回 304 空体) */
+let lastEtag = ''
+/** 合法空表也必须落地(C14):首轮成功拉取后置 true,空表不再被旧表掩盖 */
+let baselineReady = false
 
+/** 签名覆盖完整定义(name/label/description/parameters + per-agent 描述),schema-only 变更也触发刷新 */
 function toolSignature(tools) {
-  return JSON.stringify((Array.isArray(tools) ? tools : []).map(t => [t.name, t.description]))
+  return bridgeSignature(tools)
 }
 
 async function fetchTools(force = false) {
-  if (!force && toolCache.tools.length > 0 && Date.now() - toolCache.at < LIST_TTL_MS) return toolCache.tools
+  if (!force && baselineReady && Date.now() - toolCache.at < LIST_TTL_MS) return toolCache.tools
+  const headers = { 'x-aw-agent-token': AGENT_TOKEN }
+  if (lastEtag) headers['if-none-match'] = lastEtag
   const res = await fetch(`${BASE_URL}/api/workshop/agent-tools/list?agentId=${encodeURIComponent(AGENT_ID)}`, {
-    headers: { 'x-aw-agent-token': AGENT_TOKEN },
+    headers,
     signal: AbortSignal.timeout(15_000),
   })
+  // 304:工具面未变化,沿用缓存(仍需刷新 at,避免每轮都打网络)
+  if (res.status === 304) {
+    toolCache = { at: Date.now(), tools: toolCache.tools }
+    return toolCache.tools
+  }
   if (!res.ok) throw new Error(`tools/list HTTP ${res.status}`)
+  const etag = res.headers.get('etag') ?? ''
+  if (etag) lastEtag = etag
   const body = await res.json()
   const tools = body?.data?.tools ?? []
-  if (Array.isArray(tools) && tools.length > 0) toolCache = { at: Date.now(), tools }
+  // 区分 HTTP 失败与合法空数组:合法空数组必须覆盖缓存(否则解绑后旧工具永远残留)
+  if (Array.isArray(tools)) {
+    toolCache = { at: Date.now(), tools }
+    baselineReady = true
+  }
   return toolCache.tools
 }
 
@@ -59,6 +78,7 @@ const listChangedTimer = setInterval(async () => {
   try {
     const tools = await fetchTools(true)
     const sig = toolSignature(tools)
+    // baselineReady 之后任何变化(含变空)都通知;首轮只建立基线
     if (lastToolSignature && sig !== lastToolSignature) {
       process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' })}\n`)
     }

package/server/harness/aw-mcp-signature.mjs

@@ -0,0 +1,20 @@
+/**
+ * MCP bridge 工具面签名(C14):name/label/description/parameters + per-agent 描述。
+ * 抽成独立模块:桥进程与验收脚本共用同一算法,schema-only 变更也必须触发刷新。
+ */
+export function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, stableValue(value[key])]))
+  }
+  return value
+}
+
+export function toolSignature(tools) {
+  return JSON.stringify((Array.isArray(tools) ? tools : []).map(t => [
+    t.name,
+    t.label ?? '',
+    t.description ?? '',
+    stableValue(t.parameters ?? {}),
+  ]))
+}

package/server/plugins/workshop.ts

@@ -59,6 +59,7 @@ import { startAmlRetentionTimer, stopAmlRetentionTimer } from '../services/works
 import { configureMesDatasets, defaultDatasetsDir } from '../services/workshop/mes/mes-datasets'
 import { configureAnalysisRepo } from '../services/workshop/analysis/analysis.repo'
 import { configureMesHooks } from '../services/workshop/mes/mes-hook'
+import { reconcileDispatchCards } from '../services/workshop/optimization/dispatch.service'
 
 declare global {
 
@@ -152,6 +153,16 @@ export default function workshopPlugin(nitroApp: {
   configureAmlRuntime(db, dataDir)
   recoverInterruptedJobs()
   startAmlRetentionTimer()
+  // 内置训练器/问题模板真实注册(G1.4):配置驱动训练与求解都在启动即可解析
+  void import('@/server/services/workshop/process-model/trainers')
+    .then(({ registerBuiltinOptimizerAdapters }) => registerBuiltinOptimizerAdapters())
+    .catch((err) => { console.warn('[workshop] 内置优化器 Adapter 注册失败:', err instanceof Error ? err.message : err) })
+  // 环境重建前停止 Solver Worker 池(Windows venv 目录占用)
+  void import('@/server/services/workshop/optimization/worker-client')
+    .then(({ shutdownSolverWorkers }) => {
+      ;(globalThis as { __optimizerShutdownWorkers?: () => void }).__optimizerShutdownWorkers = shutdownSolverWorkers
+    })
+    .catch(() => { /* 模块不可用不阻断启动 */ })
 
   // MES 数据集服务(新表由 SCHEMA_SQL 启动建出;CSV 落 <configRoot>/datasets/<id>.csv)
   configureMesDatasets(db, defaultDatasetsDir(dataDir))
@@ -244,6 +255,15 @@ export default function workshopPlugin(nitroApp: {
   // v16 定时任务运行时:唯一周期 timer,到期触发 → submitChannelTask 下发
   manager.startScheduleRuntime()
 
+  // SW5/D14 启动对账:committed 且无 execute 审计的下发卡 → 判定 unknown/failed(禁自动重放)
+  try {
+    const reconciled = reconcileDispatchCards()
+    if (reconciled.unknown > 0) console.warn('[workshop] optimizer dispatch 对账:unknown/failed =', reconciled.unknown)
+  }
+  catch (err) {
+    console.warn('[workshop] optimizer dispatch 对账失败(不影响启动):', err instanceof Error ? err.message : err)
+  }
+
   // 全时事件录制:为全部存量 channel 建立常驻流(事件 server 驱动落库,与 client 无关)
   void ensureAllEventRecorders(manager).catch(err => console.error('[workshop] 事件录制器初始化失败:', err))
 

package/server/plugins-builtin/rag-bridge/index.mjs

@@ -279,18 +279,19 @@ export default {
     ctx.omp.registerTool({
       name: 'kb_agent',
       label: '知识库Agent',
-      description: '与 rag-knowledge 知识库的原生 Agent 对话(知识库操作唯一入口,功能解耦)。把任务原话交给它:检索问答(知识库侧自动走 QDCVR 全流程,返回带引用的可信答案)、文档入库(给出标题与完整 markdown 正文)、经验沉淀、图谱关联等,全部由知识库内部 Agent 自主处理并返回最终结果。harness/permission 一般留空(默认 claude + 最高权限)。',
+      description: '与 rag-knowledge 知识库的原生 Agent 对话(知识库操作唯一入口,功能解耦)。把任务原话交给它:检索问答(知识库侧自动走 QDCVR 全流程,返回带引用的可信答案)、文档入库(给出标题与完整 markdown 正文,action=ingest)、经验沉淀(action=ingest)、图谱关联等,全部由知识库内部 Agent 自主处理并返回最终结果。入库类动作会进入平台审批(HITL),批准后才提交。',
       parameters: {
         type: 'object',
         properties: {
           prompt: { type: 'string', description: '给知识库 Agent 的完整任务原话。检索:要查的问题;入库:目标知识库名(缺省 aw-industrial)+文档标题+完整 markdown 正文;经验:标题/类别/问题/解决方案' },
           mode: { type: 'string', enum: ['sync', 'async'], description: '执行方式(按场景自选):sync 同步等待知识库执行完并返回结果(检索问答用,需要立刻拿到答案);async 异步——立即返回 task_id,知识库在后台完成任务,完成后可用 kb_agent_status 查询该 task 的结果(入库/经验沉淀类用,无需等待)' },
-          harness: { type: 'string', description: '可选:知识库侧执行引擎(缺省 claude,一般无需填写)' },
-          permission: { type: 'string', description: '可选:权限模式(缺省 bypassPermissions 最高权限,一般无需填写)' },
+          action: { type: 'string', enum: ['query', 'ingest'], description: '动作类别:query=只读检索问答(缺省);ingest=写知识库(文档入库/经验沉淀),平台会挂 HITL 审批单,批准前不提交后端。入库务必显式声明 action=ingest。' },
         },
         required: ['prompt'],
       },
       roles: ['lead', 'worker'],
+      riskClass: 'write',
+      noRefs: true,
       handler: async (args, agent) => {
         if (!state.outbound) {
           return { text: '知识库 Agent 不可用:' + outboundOff().error + '。修复后重启服务。', isError: true }
@@ -298,11 +299,9 @@ export default {
         const prompt = String(args.prompt ?? '').trim()
         if (!prompt) return { text: 'prompt 必填(把要做的任务完整描述给知识库 Agent)。', isError: true }
         const mode = String(args.mode ?? '').trim().toLowerCase() === 'async' ? 'async' : 'sync'
-        const body = { prompt, timeout_ms: 540000, mode }
-        const harness = String(args.harness ?? '').trim()
-        if (harness) body.harness = harness
-        const permission = String(args.permission ?? '').trim()
-        if (permission) body.permission = permission
+        // 权限档由服务端固定(不再接受调用方透传):历史参数 permission/harness 一律忽略。
+        // 缺省 'default' 标准审批档;此前缺省传递 bypassPermissions 允许 Agent 自行提权。
+        const body = { prompt, timeout_ms: 540000, mode, permission: 'default' }
 
         if (mode === 'async') {
           // 异步:立即返回 task_id,知识库后台完成;结果稍后用 kb_agent_status 查询

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

@@ -1,115 +1,121 @@
-/**
- * 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>
-}
-
-/** 流式缓冲上限(超限截断并计数,防大输出/异常流拖爆内存) */
+/**
+ * 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
+  /** WP5:引用面声明(与 host-tools.json 同源;执行期由 tool-verify 实时校验) */
+  references?: import('../../tool-reference-spec').ToolVerifySpec
+  /** WP5:显式无引用声明(登记制) */
+  noRefs?: boolean
+  /** WP5:风险类别(read/write/admin) */
+  riskClass?: import('../../tool-reference-spec').ToolRiskClass
+}
+
+/** 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>
+}
+
+/** 流式缓冲上限(超限截断并计数,防大输出/异常流拖爆内存) */