@danceiny/gotry 0.0.1-rc.19 → 0.0.1-rc.21

package/ts/src/benchmark-environment-bridge.ts

@@ -1,17 +1,35 @@
 import { accessSync, constants, lstatSync, readFileSync, statSync } from 'node:fs'
 import { getuid } from 'node:process'
 import { isAbsolute } from 'node:path'
-import { defineTool } from '@deepseek-ai/dsh-tools'
+import {
+  assertSupportedJsonSchema,
+  validateJsonSchemaValue,
+  ToolArgsError,
+  type ObjectJsonSchema,
+  type ToolDefinition,
+} from '@deepseek-ai/dsh-tools'
 import {
   validateTerminalOutputConfig,
   type BenchmarkBridgeProjection,
   type TerminalOutputConfig,
 } from './benchmark-agent-conformance.ts'
 
-const SCHEMA_VERSION = 'gotry_benchmark_environment_bridge_v2'
+// v4(#215 Round 12):terminal_output 携带 closed body schema(结构关键字白名单,
+// 禁数据值注解面);v3 及更早配置缺该面,按契约不兼容 fail-closed。
+const SCHEMA_VERSION = 'gotry_benchmark_environment_bridge_v4'
+export const BENCHMARK_TOOL_RESULT_SCHEMA_VERSION = 'gotry_benchmark_tool_result_v1'
+export const BENCHMARK_DOMAIN_RECOVERIES = ['none', 'retry_same', 'revise_arguments', 'choose_alternative'] as const
+type BenchmarkDomainRecovery = typeof BENCHMARK_DOMAIN_RECOVERIES[number]
 const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]*$/
-const CONFIG_KEYS = ['allowed_tools', 'argv_prefix', 'cwd', 'enabled', 'executable', 'isolation', 'max_output_bytes', 'schema_version', 'terminal_output', 'timeout_ms']
-const OPTIONAL_CONFIG_KEYS = ['allowed_output_keys']
+const RECOVERIES = new Set<string>(BENCHMARK_DOMAIN_RECOVERIES)
+const CONFIG_KEYS = ['argv_prefix', 'cwd', 'enabled', 'executable', 'isolation', 'max_output_bytes', 'schema_version', 'terminal_output', 'timeout_ms', 'tools']
+const INPUT_SCHEMA_MAX_BYTES = 16 * 1024
+const INPUT_SCHEMA_MAX_DEPTH = 8
+const INPUT_SCHEMA_MAX_NODES = 256
+const INPUT_SCHEMA_MAX_PROPERTIES = 256
+const INPUT_SCHEMA_MAX_ENUM_VALUES = 256
+const INPUT_SCHEMA_MAX_DESCRIPTION_LENGTH = 512
+const INPUT_SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'array', 'object'])
 
 export interface BenchmarkEnvironmentBridgeConfig {
   schema_version: typeof SCHEMA_VERSION
@@ -19,8 +37,7 @@ export interface BenchmarkEnvironmentBridgeConfig {
   executable: string
   cwd: string
   argv_prefix: string[]
-  allowed_tools: string[]
-  allowed_output_keys?: Record<string, string[]>
+  tools: BenchmarkToolDescriptor[]
   timeout_ms: number
   max_output_bytes: number
   terminal_output: TerminalOutputConfig
@@ -31,10 +48,24 @@ export interface BenchmarkEnvironmentBridgeConfig {
   }
 }
 
+export interface BenchmarkToolDescriptor {
+  name: string
+  description: string
+  input_schema: ObjectJsonSchema
+  output_keys: string[]
+  domain_outcomes: Array<{ status: 'miss' | 'error'; code: string; recovery: BenchmarkDomainRecovery }>
+}
+
 function plainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+function deepFreezeJson<T>(value: T): T {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value
+  for (const child of Object.values(value as Record<string, unknown>)) deepFreezeJson(child)
+  return Object.freeze(value)
+}
+
 function existingExecutable(value: unknown): value is string {
   if (typeof value !== 'string' || !isAbsolute(value)) return false
   try {
@@ -55,17 +86,111 @@ function existingDirectory(value: unknown): value is string {
   }
 }
 
-function identifiers(value: unknown): value is string[] {
-  return Array.isArray(value) && value.length > 0 && value.length <= 64 && new Set(value).size === value.length && value.every(
+function identifiers(value: unknown, allowEmpty = false): value is string[] {
+  return Array.isArray(value) && (allowEmpty || value.length > 0) && value.length <= 64 && new Set(value).size === value.length && value.every(
     item => typeof item === 'string' && item.length > 0 && IDENTIFIER.test(item),
   )
 }
 
-function allowedOutputKeys(value: unknown, allowedTools: string[]): value is Record<string, string[]> {
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  return Object.keys(value).every(key => allowed.includes(key))
+}
+
+function validDescription(value: unknown, required = false): boolean {
+  if (value === undefined) return !required
+  return typeof value === 'string'
+    && (!required || value.trim().length > 0)
+    && value.length <= INPUT_SCHEMA_MAX_DESCRIPTION_LENGTH
+    && !/[\u0000-\u001f\u007f]/.test(value)
+}
+
+function scalarMatches(type: string, value: unknown): boolean {
+  if (type === 'string') return typeof value === 'string' && value.length <= 512
+  if (type === 'number') return typeof value === 'number' && Number.isFinite(value)
+  if (type === 'integer') return typeof value === 'number' && Number.isSafeInteger(value)
+  if (type === 'boolean') return typeof value === 'boolean'
+  return type === 'null' && value === null
+}
+
+function validInputSchema(value: unknown): value is ObjectJsonSchema {
   if (!plainObject(value)) return false
-  const keys = Object.keys(value)
-  return keys.length > 0 && keys.length <= 64
-    && keys.every(tool => allowedTools.includes(tool) && identifiers(value[tool]))
+  let serialized: string
+  try {
+    serialized = JSON.stringify(value)
+  } catch {
+    return false
+  }
+  if (Buffer.byteLength(serialized, 'utf8') > INPUT_SCHEMA_MAX_BYTES) return false
+
+  const pending: Array<{ node: Record<string, unknown>; depth: number }> = [{ node: value, depth: 0 }]
+  const seen = new Set<object>()
+  let nodes = 0
+  let properties = 0
+  let enumValues = 0
+  while (pending.length > 0) {
+    const { node, depth } = pending.pop()!
+    if (seen.has(node) || ++nodes > INPUT_SCHEMA_MAX_NODES || depth > INPUT_SCHEMA_MAX_DEPTH) return false
+    seen.add(node)
+    if (!INPUT_SCHEMA_TYPES.has(String(node.type)) || !validDescription(node.description)) return false
+
+    if (node.type === 'object') {
+      if (!exactKeys(node, ['type', 'description', 'properties', 'required', 'additionalProperties'])
+        || !plainObject(node.properties)
+        || !Array.isArray(node.required)
+        || node.additionalProperties !== false) return false
+      const propertyEntries = Object.entries(node.properties)
+      properties += propertyEntries.length
+      if (properties > INPUT_SCHEMA_MAX_PROPERTIES || propertyEntries.some(([key, child]) => !IDENTIFIER.test(key) || !plainObject(child))) return false
+      const required = node.required
+      if (required.length > propertyEntries.length
+        || new Set(required).size !== required.length
+        || required.some(key => typeof key !== 'string' || !Object.hasOwn(node.properties as Record<string, unknown>, key))) return false
+      for (const [, child] of propertyEntries) pending.push({ node: child as Record<string, unknown>, depth: depth + 1 })
+      continue
+    }
+
+    if (node.type === 'array') {
+      if (!exactKeys(node, ['type', 'description', 'items']) || !plainObject(node.items)) return false
+      pending.push({ node: node.items, depth: depth + 1 })
+      continue
+    }
+
+    if (!exactKeys(node, ['type', 'description', 'enum', 'const'])
+      || (Object.hasOwn(node, 'enum') && Object.hasOwn(node, 'const'))) return false
+    if (Object.hasOwn(node, 'const') && !scalarMatches(String(node.type), node.const)) return false
+    if (Object.hasOwn(node, 'enum')) {
+      if (!Array.isArray(node.enum) || node.enum.length === 0 || node.enum.length > 64) return false
+      enumValues += node.enum.length
+      if (enumValues > INPUT_SCHEMA_MAX_ENUM_VALUES
+        || new Set(node.enum).size !== node.enum.length
+        || node.enum.some(item => !scalarMatches(String(node.type), item))) return false
+    }
+  }
+  return value.type === 'object'
+}
+
+function toolDescriptors(value: unknown): value is BenchmarkToolDescriptor[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 64) return false
+  const names = new Set<string>()
+  return value.every(item => {
+    if (!plainObject(item)) return false
+    const keys = Object.keys(item).sort()
+    const required = ['description', 'domain_outcomes', 'input_schema', 'name']
+    if (JSON.stringify(keys) !== JSON.stringify([...required, 'output_keys'].sort())) return false
+    if (typeof item.name !== 'string' || !IDENTIFIER.test(item.name) || names.has(item.name)) return false
+    names.add(item.name)
+    if (!validDescription(item.description, true) || !validInputSchema(item.input_schema)) return false
+    if (!Array.isArray(item.domain_outcomes) || item.domain_outcomes.length > 64) return false
+    const outcomeKeys = new Set<string>()
+    if (!item.domain_outcomes.every(outcome => plainObject(outcome)
+      && JSON.stringify(Object.keys(outcome).sort()) === JSON.stringify(['code', 'recovery', 'status'])
+      && (outcome.status === 'miss' || outcome.status === 'error')
+      && typeof outcome.code === 'string' && IDENTIFIER.test(outcome.code)
+      && typeof outcome.recovery === 'string' && RECOVERIES.has(outcome.recovery)
+      && !outcomeKeys.has(outcome.code)
+      && (outcomeKeys.add(outcome.code), true))) return false
+    return identifiers(item.output_keys)
+  })
 }
 
 // These are passed as direct argv entries (never through a shell), so options
@@ -98,20 +223,19 @@ function validBound(value: unknown, maximum: number): value is number {
 function validate(value: unknown): value is BenchmarkEnvironmentBridgeConfig {
   const configKeys = plainObject(value) ? Object.keys(value).sort() : []
   const baseKeys = [...CONFIG_KEYS].sort()
-  const extendedKeys = [...CONFIG_KEYS, ...OPTIONAL_CONFIG_KEYS].sort()
   if (!plainObject(value)
-    || ![baseKeys, extendedKeys].some(keys => JSON.stringify(configKeys) === JSON.stringify(keys))
+    || JSON.stringify(configKeys) !== JSON.stringify(baseKeys)
     || value.schema_version !== SCHEMA_VERSION
     || value.enabled !== true
     || !existingExecutable(value.executable)
     || !existingDirectory(value.cwd)
     || !argvPrefix(value.argv_prefix)
-    || !identifiers(value.allowed_tools)
+    || !toolDescriptors(value.tools)
     || !validBound(value.timeout_ms, 120_000)
     || !validBound(value.max_output_bytes, 10 * 1024 * 1024)
     || !validateTerminalOutputConfig(value.terminal_output)
     || !exactIsolation(value.isolation)
-    || (Object.hasOwn(value, 'allowed_output_keys') && !allowedOutputKeys(value.allowed_output_keys, value.allowed_tools))) return false
+    ) return false
   return true
 }
 
@@ -124,13 +248,13 @@ export function loadBenchmarkEnvironmentConfig(path: string): BenchmarkEnvironme
     if (typeof getuid !== 'function' || metadata.uid !== getuid()) return null
     if ((metadata.mode & 0o022) !== 0) return null
     const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return validate(parsed) ? parsed : null
+    return validate(parsed) ? deepFreezeJson(parsed) : null
   } catch {
     return null
   }
 }
 
-type Register = (tool: ReturnType<typeof defineTool>) => void
+type Register = (tool: ToolDefinition) => void
 interface CollectedText {
   readFrom(offset: number): { text: string; nextOffset: number; lossy?: boolean }
 }
@@ -176,6 +300,19 @@ const FORBIDDEN_OUTPUT_KEY_FRAGMENTS = [
   'loadermetadata', 'oracle', 'reference', 'reward', 'score',
 ]
 
+export const BRIDGE_ERROR_CONTRACT: Record<string, { recoverable: boolean; remedy: string }> = Object.freeze({
+  invalid_action: { recoverable: true, remedy: 'action 只允许 tools、call 或 errors' },
+  disallowed_tool: { recoverable: true, remedy: '先 action=tools 列出 allowed_tools 清单,再从清单内选工具' },
+  invalid_arguments: { recoverable: true, remedy: 'arguments 必须是可序列化 JSON 对象(≤64KB、深度≤12);收窄后重试' },
+  timed_out: { recoverable: true, remedy: '上游超时;可原样重试一次或换其他工具' },
+  output_truncated: { recoverable: true, remedy: '输出超出上限;让被调工具收窄查询范围后重试' },
+  invalid_json: { recoverable: true, remedy: '上游输出不是合法 JSON;重试一次或换工具' },
+  invalid_output: { recoverable: true, remedy: '上游输出结构不符;重试或换工具' },
+  runner_failed: { recoverable: true, remedy: '上游进程非零退出;可重试一次,持续失败换工具' },
+  spawn_failed: { recoverable: false, remedy: '可执行文件不可用——环境问题,调用方不可恢复' },
+  forbidden_output: { recoverable: false, remedy: '输出含未授权键(策略边界)——不可恢复,换工具或放弃' },
+})
+
 function inspectOutput(value: unknown): 'ok' | 'forbidden_key' | 'structure_limit' {
   const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }]
   let nodes = 0
@@ -199,19 +336,22 @@ function inspectOutput(value: unknown): 'ok' | 'forbidden_key' | 'structure_limi
 
 function inspectAllowedOutput(value: unknown, allowedKeys: string[]): boolean {
   const allowed = new Set(allowedKeys)
-  const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }]
+  const pending: Array<{ value: unknown; depth: number; coveredByDeclaredKey: boolean }> = [{ value, depth: 0, coveredByDeclaredKey: false }]
   let nodes = 0
   while (pending.length > 0) {
     const current = pending.pop()!
     if (++nodes > 10_000 || current.depth > 24) return false
     if (Array.isArray(current.value)) {
-      for (const child of current.value) pending.push({ value: child, depth: current.depth + 1 })
+      for (const child of current.value) pending.push({ value: child, depth: current.depth + 1, coveredByDeclaredKey: current.coveredByDeclaredKey })
+      continue
+    }
+    if (!plainObject(current.value)) {
+      if (!current.coveredByDeclaredKey) return false
       continue
     }
-    if (!plainObject(current.value)) continue
     for (const [key, child] of Object.entries(current.value)) {
       if (!allowed.has(key)) return false
-      pending.push({ value: child, depth: current.depth + 1 })
+      pending.push({ value: child, depth: current.depth + 1, coveredByDeclaredKey: true })
     }
   }
   return true
@@ -244,21 +384,6 @@ function serializedArguments(value: Record<string, unknown>): { json: string; re
   }
 }
 
-/** 可恢复 domain-error 契约(Round 8,issue #100/#102):封闭词表 + 逐码可恢复性与补救指引。
- *  模型经 action=errors 拉取全表;失败返回的扁平形状保持不变(benchmark 诊断面依赖)。 */
-export const BRIDGE_ERROR_CONTRACT: Record<string, { recoverable: boolean; remedy: string }> = Object.freeze({
-  invalid_action: { recoverable: true, remedy: 'action 只允许 tools 或 call' },
-  disallowed_tool: { recoverable: true, remedy: '先 action=tools 列出 allowed_tools 清单,再从清单内选工具' },
-  invalid_arguments: { recoverable: true, remedy: 'arguments 必须是可序列化 JSON 对象(≤64KB、深度≤12);收窄后重试' },
-  timed_out: { recoverable: true, remedy: '上游超时;可原样重试一次或换其他工具' },
-  output_truncated: { recoverable: true, remedy: '输出超出上限;让被调工具收窄查询范围后重试' },
-  invalid_json: { recoverable: true, remedy: '上游输出不是合法 JSON;重试一次或换工具' },
-  invalid_output: { recoverable: true, remedy: '上游输出结构不符(如原始字符串);重试或换工具' },
-  runner_failed: { recoverable: true, remedy: '上游进程非零退出;可重试一次,持续失败换工具' },
-  spawn_failed: { recoverable: false, remedy: '可执行文件不可用——环境问题,调用方不可恢复' },
-  forbidden_output: { recoverable: false, remedy: '输出含未授权键(策略边界)——不可恢复,换工具或放弃' },
-})
-
 /** Register the opt-in model-facing bridge. */
 export function registerBenchmarkEnvironmentBridge(
   path: string,
@@ -269,35 +394,57 @@ export function registerBenchmarkEnvironmentBridge(
   if (!bridge) throw new Error('benchmark environment bridge configuration unavailable')
   if (!subprocess) throw new Error('benchmark environment bridge subprocess unavailable')
 
-  register(defineTool({
-    name: 'gotry_benchmark_environment',
-    description: 'When a prompt asks to run agent_env.cli, use action=call here with the mapped tool; arbitrary shell is not exposed. '
-      + 'Recoverable domain-error contract: every failure returns { ok:false, error:<code>, ... } from a closed vocabulary; '
-      + 'call action=errors to fetch the per-code recoverable flag and remedy before retrying.',
-    // Round 8(issue #100/#102):generic typed schema——模型可见逐字段契约(与产品面 D-30 同刀法);
-    // arguments 保持 additionalProperties:true(被调工具的参数面由其自身契约定义)
-    parameters: {
-      action: { type: 'string', enum: ['tools', 'call', 'errors'], required: true, description: 'tools=列出可调工具;call=执行被映射工具;errors=拉取可恢复错误契约表' },
-      tool: { type: 'string', description: '被调工具名(必须在 allowed_tools 清单内;action=call 时必填)' },
-      arguments: { type: 'object', additionalProperties: true, description: '传给被调工具的参数对象(action=call 时可选;≤64KB、深度≤12)' },
+  const parameters: Record<string, unknown> = deepFreezeJson({
+    type: 'object',
+    description: 'Flat benchmark bridge wire: choose an action, then provide the mapped tool and its arguments.',
+    properties: {
+      action: { type: 'string', enum: ['tools', 'call', 'errors'], description: 'tools=列出可调工具;call=执行工具;errors=拉取错误契约' },
+      tool: { type: 'string', enum: bridge.tools.map(item => item.name), description: 'action=call 时选择的冻结工具名' },
+      arguments: { type: 'object', additionalProperties: true, description: 'action=call 时传给工具的参数对象' },
     },
+    required: ['action'],
+    additionalProperties: false,
+  })
+  assertSupportedJsonSchema(parameters)
+
+  const definition: ToolDefinition = {
+    name: 'gotry_benchmark_environment',
+    description: 'When a prompt asks to run agent_env.cli, use action=call here with the mapped tool; arbitrary shell is not exposed.',
+    parameters,
     output: {
-      schema: { type: 'json' },
+      schema: {},
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
     },
-    async execute(args): Promise<Record<string, never>> {
-      const action = args?.action
-      if (action === 'errors') return jsonObject({ ok: true, errors: BRIDGE_ERROR_CONTRACT })
-      if (action === 'tools') return jsonObject({ ok: true, tools: bridge.allowed_tools })
-      if (action !== 'call') return jsonObject({ ok: false, error: 'invalid_action' })
-      const query = args as unknown as { tool?: unknown; arguments?: unknown }
-      if (typeof query.tool !== 'string' || !bridge.allowed_tools.includes(query.tool)) {
+    async execute(args: unknown): Promise<Record<string, never>> {
+      const violations = validateJsonSchemaValue(parameters, args, 'arguments')
+      if (violations.length > 0) throw new ToolArgsError(violations)
+      const query = args as Record<string, unknown>
+      const tool = query.tool
+      const descriptor = bridge.tools.find(item => item.name === tool)
+      const keys = Object.keys(query)
+      if (query.action === 'tools') {
+        if (keys.length !== 1) throw new ToolArgsError(['arguments: tools action accepts no tool or arguments'])
+        return jsonObject({ ok: true, tools: bridge.tools })
+      }
+      if (query.action === 'errors') {
+        if (keys.length !== 1) throw new ToolArgsError(['arguments: errors action accepts no tool or arguments'])
+        return jsonObject({ ok: true, errors: BRIDGE_ERROR_CONTRACT })
+      }
+      if (query.action !== 'call') {
+        return jsonObject({ ok: false, error: 'invalid_action' })
+      }
+      if (keys.length !== 3 || !Object.hasOwn(query, 'tool') || !Object.hasOwn(query, 'arguments')) {
+        throw new ToolArgsError(['arguments: call action requires exactly tool and arguments'])
+      }
+      if (typeof tool !== 'string' || !descriptor) {
         return jsonObject({ ok: false, error: 'disallowed_tool' })
       }
-      if (query.arguments !== undefined && !plainObject(query.arguments)) {
+      if (!plainObject(query.arguments)) {
         return jsonObject({ ok: false, error: 'invalid_arguments' })
       }
-      const callArguments = query.arguments === undefined ? {} : query.arguments
+      const callArguments = query.arguments
+      const argumentViolations = validateJsonSchemaValue(descriptor.input_schema, callArguments, 'arguments')
+      if (argumentViolations.length > 0) throw new ToolArgsError(argumentViolations)
       const serialized = serializedArguments(callArguments)
       if (serialized.reason) return jsonObject({ ok: false, error: 'invalid_arguments', reason: serialized.reason })
       const controller = new AbortController()
@@ -315,7 +462,7 @@ export function registerBenchmarkEnvironmentBridge(
         env.PYTHONDONTWRITEBYTECODE = '1'
         env.PYTHONNOUSERSITE = '1'
         handle = subprocess.spawn({
-          argv: [bridge.executable, ...bridge.argv_prefix, 'call', query.tool, serialized.json!],
+          argv: [bridge.executable, ...bridge.argv_prefix, 'call', tool, serialized.json!],
           cwd: bridge.cwd,
           stdio: {
             stdin: 'ignore',
@@ -344,12 +491,18 @@ export function registerBenchmarkEnvironmentBridge(
         const outputInspection = inspectOutput(parsed)
         if (outputInspection === 'forbidden_key') return jsonObject({ ok: false, error: 'forbidden_output' })
         if (outputInspection === 'structure_limit') return jsonObject({ ok: false, error: 'invalid_output' })
-        const visibleResult = parsed.result ?? parsed
+        if (parsed.schema_version !== BENCHMARK_TOOL_RESULT_SCHEMA_VERSION || typeof parsed.status !== 'string') {
+          return jsonObject({ ok: false, error: 'invalid_output' })
+        }
+        if (parsed.status === 'miss' || parsed.status === 'error') {
+          if (typeof parsed.code !== 'string' || typeof parsed.recovery !== 'string' || !descriptor.domain_outcomes.some(outcome => outcome.status === parsed.status && outcome.code === parsed.code && outcome.recovery === parsed.recovery)) return jsonObject({ ok: false, error: 'invalid_output' })
+          if (Object.keys(parsed).sort().join(',') !== 'code,recovery,schema_version,status') return jsonObject({ ok: false, error: 'invalid_output' })
+          return jsonObject({ ok: true, outcome: parsed })
+        }
+        if (parsed.status !== 'ok' || !Object.hasOwn(parsed, 'result') || Object.keys(parsed).sort().join(',') !== 'result,schema_version,status') return jsonObject({ ok: false, error: 'invalid_output' })
+        const visibleResult = parsed.result
         if (!plainObject(visibleResult) && !Array.isArray(visibleResult)) return jsonObject({ ok: false, error: 'invalid_output' })
-        const outputKeys = bridge.allowed_output_keys && Object.hasOwn(bridge.allowed_output_keys, query.tool)
-          ? bridge.allowed_output_keys[query.tool]
-          : undefined
-        if (outputKeys && !inspectAllowedOutput(visibleResult, outputKeys)) return jsonObject({ ok: false, error: 'forbidden_output' })
+        if (!inspectAllowedOutput(visibleResult, descriptor.output_keys)) return jsonObject({ ok: false, error: 'forbidden_output' })
         return jsonObject({ ok: true, result: visibleResult })
       } catch {
         if (controller.signal.aborted) return jsonObject({ ok: false, error: 'timed_out' })
@@ -358,10 +511,11 @@ export function registerBenchmarkEnvironmentBridge(
         clearTimeout(timer)
       }
     },
-  }))
+  }
+  register(definition)
   return Object.freeze({
     toolName: 'gotry_benchmark_environment',
-    allowedTools: Object.freeze([...bridge.allowed_tools]),
+    allowedTools: Object.freeze(bridge.tools.map(item => item.name)),
     terminal: Object.freeze({ ...bridge.terminal_output }),
   })
 }

package/ts/src/booking-surface/dsh-planner.ts

@@ -407,9 +407,11 @@ function recoverFinalResponseDecision(response: string, task: BookingCopilotTask
     console.error('[booking-copilot] finalResponse recovery rejected (invalid action):', JSON.stringify({ kind: action.kind, errors: validation.errors.slice(0, 6) }).slice(0, 600))
     return null
   }
-  repairPlannerFactRefs(action)
+  const repairedRefs = repairPlannerFactRefs(action)
+  const repairedValidation = validateBookingReadAction(action as unknown as BookingReadAction)
+  if (!repairedValidation.ok) return null
   try {
-    assertPlannerSafeRefs(action)
+    assertPlannerSafeRefs(action, repairedRefs)
   } catch (error) {
     console.error('[booking-copilot] finalResponse recovery rejected (unsafe ref):', JSON.stringify({ actionId: action.actionId, factRefs: action.factRefs }).slice(0, 600))
     return null
@@ -426,17 +428,22 @@ function recoverFinalResponseDecision(response: string, task: BookingCopilotTask
 const PLANNER_SAFE_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9:._-]*$/
 
 // Models cite prompt facts in URI-ish syntax (`fact://turn_X/request`,
-// `turn_X#request`); characters outside the runtime ref charset are mapped
-// deterministically to '.' so repair succeeds without burning the retry
-// budget. Anything the sanitizer cannot make unique enough still fails the
-// safe-ref gate into the retry path.
-function repairPlannerFactRefs(action: Record<string, unknown>): void {
+// `turn_X#request`). Preserve already-safe refs exactly; unsafe refs enter the
+// reserved modelref namespace with the full SHA-256 of the raw UTF-8 value.
+function repairPlannerFactRefs(action: Record<string, unknown>): Set<string> {
   const factRefs = action.factRefs
-  if (!Array.isArray(factRefs)) return
-  action.factRefs = factRefs.map((ref) => (typeof ref === 'string' ? ref.replace(/#/g, ':').replace(/[^A-Za-z0-9:._-]/g, '.') : ref))
+  const repairedRefs = new Set<string>()
+  if (!Array.isArray(factRefs)) return repairedRefs
+  action.factRefs = factRefs.map((ref) => {
+    if (typeof ref !== 'string' || PLANNER_SAFE_REF_PATTERN.test(ref)) return ref
+    const alias = `modelref:${createHash('sha256').update(ref, 'utf8').digest('hex')}`
+    repairedRefs.add(alias)
+    return alias
+  })
+  return repairedRefs
 }
 
-function assertPlannerSafeRefs(action: Record<string, unknown>): void {
+function assertPlannerSafeRefs(action: Record<string, unknown>, repairedRefs: Set<string>): void {
   const actionId = action.actionId
   if (typeof actionId !== 'string' || !PLANNER_SAFE_REF_PATTERN.test(actionId)) {
     throw new Error(`planner_invalid_action:unsafe_action_id:${String(actionId).slice(0, 60)}`)
@@ -444,7 +451,7 @@ function assertPlannerSafeRefs(action: Record<string, unknown>): void {
   const factRefs = action.factRefs
   if (Array.isArray(factRefs)) {
     for (const ref of factRefs) {
-      if (typeof ref !== 'string' || !PLANNER_SAFE_REF_PATTERN.test(ref)) {
+      if (typeof ref !== 'string' || !PLANNER_SAFE_REF_PATTERN.test(ref) || (ref.startsWith('modelref:') && !repairedRefs.has(ref)) || ref.length > 512) {
         throw new Error(`planner_invalid_action:unsafe_fact_ref:${String(ref).slice(0, 60)}`)
       }
     }
@@ -502,8 +509,13 @@ function parseToolDecision(event: unknown, task: BookingCopilotTaskState): Booki
   // boundary, past the retry budget. Repair the common fragment syntax first,
   // then enforce the same charset here so remaining violations retry as
   // parse-class failures instead of failing the turn as PLANNER_FAILED.
-  repairPlannerFactRefs(decision.action)
-  assertPlannerSafeRefs(decision.action)
+  const repairedRefs = repairPlannerFactRefs(decision.action)
+  const repairedValidation = validateBookingReadAction(decision.action)
+  if (!repairedValidation.ok) {
+    console.error(`[booking-copilot] repaired action rejected:`, JSON.stringify({ errors: repairedValidation.errors.slice(0, 8) }).slice(0, 800))
+    throw new Error(`planner_invalid_action:${repairedValidation.errors.join('; ')}`)
+  }
+  assertPlannerSafeRefs(decision.action, repairedRefs)
   const action = decision.action as unknown as BookingReadAction
   const capability = TOOL_TO_CAPABILITY.get(name as DshEmbeddedBookingToolName)
   if (!capability || !actionsForEmbeddedCapability(capability).includes(action.kind)) {

package/ts/src/index.ts

@@ -1210,14 +1210,16 @@ export function apply(ctx: Context, config: Config): void {
       if (!q.keyword) {
         return JSON.parse(JSON.stringify({ ok: false, verdict: 'error', summary: 'keyword 必填', evidence: '[hbcli-anything@error] empty' })) as Record<string, never>
       }
-      const itpA = await interpretEffect({ effect: 'ANYTHING_SEARCH', params: q })
+      // hbcliBin 直通 config(缺省 'hbcli',能力层按已知安装位回退)——issue #195 教训:
+      // 此前 params 只透 q,config.hbcliBin 永远到不了能力层
+      const itpA = await interpretEffect({ effect: 'ANYTHING_SEARCH', params: { ...q, hbcliBin: config.hbcliBin } })
       if (!itpA.result) return declinedObservation('ANYTHING_SEARCH', itpA.trace)
       const r = itpA.result
       const dir = await ensureStateDir(config.stateRoot)
       await recordLatency(join(dir, 'bridge-latency.jsonl'), Date.now() - started, `anything:${r.via}`).catch(() => {})
       const top5 = (r.hits ?? []).slice(0, 5)
       const summary = r.verdict === 'hit'
-        ? `${q.keyword} → hit (${r.hits?.length ?? 0} 候选项)\n${top5.map((h, i) => `  ${i + 1}. [${h.type}] ${h.name}${h.latitude !== undefined && h.longitude !== undefined ? ` @ (${h.latitude.toFixed(3)},${h.longitude.toFixed(3)})` : ''}`).join('\n')}\n${r.evidence}`
+        ? `${q.keyword} → hit (${r.hits?.length ?? 0} 候选项)\n${top5.map((h, i) => `  ${i + 1}. [${h.type}] ${h.name}${h.star ? ` ${h.star}★` : ''}${h.latitude !== undefined && h.longitude !== undefined ? ` @ (${h.latitude.toFixed(3)},${h.longitude.toFixed(3)})` : ''}${h.hotelId ? ` hotelId=${h.hotelId}` : h.destinationId ? ` destinationId=${h.destinationId}` : ''}`).join('\n')}\n${r.evidence}`
         : r.verdict === 'miss'
           ? `${q.keyword} → miss (酒店-be 一切正常但无候选)\n${r.evidence}`
           : `${q.keyword} → unavailable (${r.error})\n${r.evidence}`

package/ts/src/turn-deadline.ts

@@ -22,6 +22,10 @@ import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+// 类型面显式依赖:session/event、session/disposed 的事件表声明在 dsh-session 的
+// cordis Events augmentation 里——不显式导入时,该声明只在 peer 恰好物化进
+// ts/node_modules 的机器上可见(legacy-peer-deps 安装则缺,5 个 TS2345/TS7006)。
+import type {} from '@deepseek-ai/dsh-session'
 import type { ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { classifyTurn, TURN_HANDOFF_ETA_LABEL, turnPolicyFor, type TurnPolicy } from './turn-policy.ts'