dsh-ptc-plus 0.4.10 → 0.5.1

package/internal/capability-statistics.js

@@ -0,0 +1,214 @@
+const CATEGORIES = new Set(['tool', 'skill', 'resource', 'resource-template', 'task'])
+const OUTCOMES = new Set(['complete', 'failed', 'cancelled', 'unknown'])
+const USE_EVIDENCE = new Map([
+  ['tool', 'host-execution-result'], ['task', 'host-execution-result'], ['skill', 'skill-body-accepted'],
+  ['resource', 'resource-access'], ['resource-template', 'resource-access'],
+])
+
+function fail(label) { throw new TypeError(`ptc-plus: invalid capability statistics ${label}`) }
+function record(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(label)
+  return value
+}
+function identity(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 4096) fail(label)
+  return value
+}
+function integer(value, label, minimum = 0) {
+  if (!Number.isSafeInteger(value) || value < minimum) fail(label)
+  return value
+}
+function key(value) { return JSON.stringify(value) }
+function orderSamples(a, b) { return b.eligibleOrder - a.eligibleOrder }
+function freeze(value) {
+  if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) freeze(item)
+    Object.freeze(value)
+  }
+  return value
+}
+
+/** Bounds are explicit calibration inputs; no observation, clock or process directory is inferred. */
+export function createCapabilityStatistics(configuration) {
+  const options = record(configuration, 'configuration')
+  const limits = {}
+  for (const name of ['windowSize', 'maxFamilies', 'maxScopes', 'maxCapabilitiesPerFamily']) limits[name] = integer(options[name], name, 1)
+  return freeze({ schema: 'ptc-capability-statistics/v1', status: 'usable', limits, families: [], windows: [] })
+}
+
+function observation(raw) {
+  const value = record(raw, 'availability observation')
+  const category = value.category
+  if (!CATEGORIES.has(category)) fail('category')
+  if (!['full', 'on-demand', 'host'].includes(value.disclosure)) fail('availability disclosure')
+  const useEvidence = value.useEvidence ?? null
+  if (useEvidence !== null && useEvidence !== USE_EVIDENCE.get(category)) fail('owner use evidence')
+  const outcome = useEvidence === null ? null : value.outcome ?? 'unknown'
+  if (outcome !== null && !OUTCOMES.has(outcome)) fail('owner outcome evidence')
+  return {
+    workspaceId: identity(value.workspaceId, 'workspace identity'),
+    id: identity(value.id, 'capability identity'), revision: identity(value.revision, 'capability revision'), category,
+    disclosure: value.disclosure, planRevision: identity(value.planRevision, 'plan revision'),
+    used: useEvidence !== null, outcome,
+  }
+}
+
+function sampleObservation(value) {
+  const item = record(value, 'retained observation')
+  identity(item.workspaceId, 'retained workspace identity')
+  identity(item.id, 'retained capability identity')
+  identity(item.revision, 'retained capability revision')
+  if (!CATEGORIES.has(item.category) || typeof item.used !== 'boolean' || !Array.isArray(item.exposures) || item.exposures.length < 1) fail('retained evidence')
+  if (!Array.isArray(item.outcomes) || item.outcomes.some(outcome => !OUTCOMES.has(outcome))
+    || new Set(item.outcomes).size !== item.outcomes.length || item.used !== (item.outcomes.length > 0)) fail('retained outcomes')
+  for (const exposure of item.exposures) {
+    record(exposure, 'retained exposure')
+    if (!['full', 'on-demand', 'host'].includes(exposure.disclosure)) fail('retained disclosure')
+    identity(exposure.planRevision, 'retained plan revision')
+  }
+}
+
+/** Validate retained state before it can supply an automatic-allocation denominator. */
+export function validateCapabilityStatistics(state) {
+  const value = record(state, 'state')
+  if (value.schema !== 'ptc-capability-statistics/v1' || !['usable', 'capacity-exceeded'].includes(value.status)) fail('state schema or status')
+  const template = createCapabilityStatistics(value.limits)
+  if (!Array.isArray(value.families) || !Array.isArray(value.windows)
+    || value.families.length > template.limits.maxFamilies || value.windows.length > template.limits.maxScopes) fail('state bounds')
+  const familyKeys = new Set()
+  const orders = new Set()
+  for (const family of value.families) {
+    record(family, 'retained family')
+    const familyKey = key([identity(family.userId, 'user identity'), identity(family.familyId, 'family identity')])
+    if (familyKeys.has(familyKey)) fail('duplicate family')
+    familyKeys.add(familyKey)
+    integer(family.observationRevision, 'observation revision')
+    if (!['active', 'settled', 'unknown'].includes(family.settlement)) fail('family settlement')
+    if (family.eligibleOrder !== null) {
+      integer(family.eligibleOrder, 'qualification order', 1)
+      const orderKey = key([family.userId, family.eligibleOrder])
+      if (orders.has(orderKey)) fail('duplicate qualification order')
+      orders.add(orderKey)
+    } else if (family.settlement === 'settled') fail('settled family without qualification order')
+    if (!Array.isArray(family.observations) || family.observations.length > value.limits.maxCapabilitiesPerFamily) fail('family observation bounds')
+    const observationKeys = new Set()
+    for (const item of family.observations) {
+      sampleObservation(item)
+      const observationKey = key([item.workspaceId, item.id, item.revision])
+      if (observationKeys.has(observationKey)) fail('duplicate observation')
+      observationKeys.add(observationKey)
+      if (item.exposures.length > value.limits.maxCapabilitiesPerFamily) fail('exposure bounds')
+    }
+  }
+  const windowKeys = new Set()
+  for (const window of value.windows) {
+    record(window, 'window')
+    identity(window.userId, 'window user identity')
+    if (window.workspaceId !== null) identity(window.workspaceId, 'window workspace identity')
+    identity(window.id, 'window capability identity')
+    identity(window.revision, 'window capability revision')
+    integer(window.floor, 'evicted qualification frontier')
+    const windowKey = key([window.userId, window.workspaceId, window.id, window.revision])
+    if (windowKeys.has(windowKey)) fail('duplicate window')
+    windowKeys.add(windowKey)
+  }
+  return value
+}
+
+function windowKey(userId, workspaceId, item) { return key([userId, workspaceId, item.id, item.revision]) }
+function qualifies(family, window) {
+  return family.userId === window.userId && family.settlement === 'settled' && family.eligibleOrder > window.floor
+    && family.observations.some(item => item.id === window.id && item.revision === window.revision
+      && (window.workspaceId === null || item.workspaceId === window.workspaceId))
+}
+
+/**
+ * Public adapters supply actual family/workspace identities, monotone observation revisions,
+ * and an immutable qualification order. Observations are cumulative additions, never log guesses.
+ * A resumed or unknown family contributes no negative sample until owner-proven settlement.
+ */
+export function reduceCapabilityStatistics(previous, event) {
+  validateCapabilityStatistics(previous)
+  if (previous.status !== 'usable') return previous
+  const value = record(event, 'event')
+  if (value.type !== 'family-observation') fail('event type')
+  const userId = identity(value.userId, 'user identity')
+  const familyId = identity(value.familyId, 'family identity')
+  const observationRevision = integer(value.observationRevision, 'observation revision')
+  const settlement = value.settlement
+  if (!['active', 'settled', 'unknown'].includes(settlement)) fail('family settlement')
+  const eligibleOrder = value.eligibleOrder == null ? null : integer(value.eligibleOrder, 'qualification order', 1)
+  if (settlement === 'settled' && eligibleOrder === null) fail('settlement qualification order')
+  if (!Array.isArray(value.observations) || value.observations.length > previous.limits.maxCapabilitiesPerFamily) fail('observation bounds')
+  const additions = value.observations.map(observation)
+  const state = structuredClone(previous)
+  let family = state.families.find(item => item.userId === userId && item.familyId === familyId)
+  if (family) {
+    if (family.eligibleOrder !== null && eligibleOrder !== family.eligibleOrder) fail('changed qualification order')
+    if (observationRevision <= family.observationRevision) return previous
+    family.observationRevision = observationRevision
+    family.settlement = settlement
+    family.eligibleOrder ??= eligibleOrder
+  } else {
+    if (eligibleOrder !== null && state.families.some(item => item.userId === userId && item.eligibleOrder === eligibleOrder)) fail('qualification order collision')
+    family = { userId, familyId, observationRevision, settlement, eligibleOrder, observations: [] }
+    state.families.push(family)
+  }
+  for (const addition of additions) {
+    let retained = family.observations.find(item => item.workspaceId === addition.workspaceId && item.id === addition.id && item.revision === addition.revision)
+    if (!retained) {
+      retained = { workspaceId: addition.workspaceId, id: addition.id, revision: addition.revision, category: addition.category, used: false, exposures: [], outcomes: [] }
+      family.observations.push(retained)
+    } else if (retained.category !== addition.category) fail('changed capability category')
+    retained.used ||= addition.used
+    if (addition.outcome !== null && !retained.outcomes.includes(addition.outcome)) retained.outcomes.push(addition.outcome)
+    const exposure = { disclosure: addition.disclosure, planRevision: addition.planRevision }
+    if (!retained.exposures.some(item => item.disclosure === exposure.disclosure && item.planRevision === exposure.planRevision)) retained.exposures.push(exposure)
+    for (const workspaceId of [addition.workspaceId, null]) {
+      const targetKey = windowKey(userId, workspaceId, addition)
+      if (!state.windows.some(item => windowKey(item.userId, item.workspaceId, item) === targetKey)) {
+        state.windows.push({ userId, workspaceId, id: addition.id, revision: addition.revision, floor: 0 })
+      }
+    }
+  }
+  const retainedFamilies = new Set()
+  for (const window of state.windows) {
+    const eligible = state.families.filter(item => qualifies(item, window)).sort(orderSamples)
+    const selected = eligible.slice(0, state.limits.windowSize)
+    for (const item of selected) retainedFamilies.add(key([item.userId, item.familyId]))
+    for (const item of eligible.slice(state.limits.windowSize)) window.floor = Math.max(window.floor, item.eligibleOrder)
+  }
+  state.families = state.families.filter(item => item.settlement !== 'settled' || retainedFamilies.has(key([item.userId, item.familyId])))
+  if (state.families.length > state.limits.maxFamilies || state.windows.length > state.limits.maxScopes
+    || state.families.some(item => item.observations.length > state.limits.maxCapabilitiesPerFamily
+      || item.observations.some(entry => entry.exposures.length > state.limits.maxCapabilitiesPerFamily))) {
+    return freeze({ ...structuredClone(previous), status: 'capacity-exceeded' })
+  }
+  validateCapabilityStatistics(state)
+  return freeze(state)
+}
+
+/** Per-capability eligible windows; workspace and global evidence are never added together. */
+export function capabilityCoverage(state, query) {
+  validateCapabilityStatistics(state)
+  const options = record(query, 'coverage query')
+  const userId = identity(options.userId, 'coverage user identity')
+  const id = identity(options.id, 'coverage capability identity')
+  const revision = identity(options.revision, 'coverage capability revision')
+  const workspaceId = options.workspaceId === null ? null : identity(options.workspaceId, 'coverage workspace identity')
+  if (state.status !== 'usable') return { status: state.status, windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
+  const window = state.windows.find(item => item.userId === userId && item.workspaceId === workspaceId && item.id === id && item.revision === revision)
+  // "Nothing recorded yet" and "recorded families are not currently settled"
+  // are different facts from a measured window; neither may read as a zero.
+  if (window === undefined) return { status: 'no-samples', windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
+  const families = state.families.filter(item => qualifies(item, window)).sort(orderSamples).slice(0, state.limits.windowSize)
+  // A resumed family can expose a gap behind the irreversible eviction frontier.
+  // Surviving samples do not prove the recent settled window until it is full again.
+  if (window.floor > 0 && families.length < state.limits.windowSize) {
+    return { status: 'incomplete-window', windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
+  }
+  if (families.length === 0) return { status: 'pending-settlement', windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
+  const used = families.filter(family => family.observations.some(item => item.id === id && item.revision === revision && item.used
+    && (workspaceId === null || item.workspaceId === workspaceId))).length
+  return { status: 'usable', windowSize: state.limits.windowSize, eligible: families.length, used, coverage: families.length ? used / families.length : null }
+}

package/internal/config-spec.js

@@ -1,3 +1,5 @@
+import { CAPABILITY_POLICY_DEFAULT } from './capability-policy.js'
+
 /** Configuration fields shared by the Host schema and settings card. */
 export const MAX_TIMER_DELAY_MS = 2_147_483_647
 
@@ -11,6 +13,54 @@ export const SETTINGS_NAMESPACE = 'ptc-plus'
  * exists in both locales or in neither.
  */
 export const CONFIG_FIELDS = Object.freeze([
+  { key: 'capabilityContextEnabled', type: 'boolean', default: true,
+    label: '能力与上下文', labelEn: 'Capabilities and context',
+    description: '整体暂停能力规则、统计采集、说明恢复和结果预览，保留各项设置；新会话或明确刷新后生效。',
+    descriptionEn: 'Pauses capability rules, statistics collection, description recovery and result previews while retaining each setting. Applies to new sessions or explicit refreshes.' },
+  { key: 'capabilityManagementEnabled', type: 'boolean', default: false,
+    label: '实验性能力管理', labelEn: 'Experimental capability management',
+    description: '为新 PTC 会话应用可用性与说明规则；已有会话使用 /capabilities refresh 生效。收益尚未经过模型对照验收。',
+    descriptionEn: 'Applies availability and disclosure rules to new PTC sessions. Use /capabilities refresh for existing sessions. Model cost benefits remain unverified.' },
+  { key: 'capabilityPolicy', preserveOmission: true, type: 'string', default: CAPABILITY_POLICY_DEFAULT,
+    label: '能力规则', labelEn: 'Capability rules',
+    description: '分别设置可用性、说明方式以及常用集、统计和预算分配；默认、类别、MCP 来源、单项依次覆盖。',
+    descriptionEn: 'Choose availability, disclosure and baseline, statistics and budget allocation separately. Default, category, MCP source and item rules apply in order.' },
+  { key: 'capabilityRecoveryEnabled', preserveOmission: true, type: 'boolean', default: false,
+    label: '压缩后恢复已使用的 API 说明', labelEn: 'Recover used API descriptions after compaction',
+    description: '只补回已展开、仍有效且不可见的近期 API 说明，不恢复 Skill 正文。',
+    descriptionEn: 'Restores only expanded, current, no longer visible API descriptions from recent use; never Skill bodies.' },
+  { key: 'modelPreviewEnabled', preserveOmission: true, type: 'boolean', default: false,
+    label: '限制模型侧结果与日志展示', labelEn: 'Bound model-facing results and logs',
+    description: '独立使用插件预览预算；关闭时沿用宿主展示，程序值始终完整。',
+    descriptionEn: 'Independently selects the plugin preview budget. Otherwise retains Host presentation; program values remain complete.' },
+  { key: 'capabilityBaseline', type: 'string', default: '[]',
+    label: '初始常用能力', labelEn: 'Initial common capabilities',
+    description: '从能力列表勾选常用项；adaptive 选用常用集依据时参与分配，不生成使用记录。',
+    descriptionEn: 'Select common capabilities as an optional allocation basis for adaptive disclosure. Creates no usage records.' },
+  { key: 'capabilityOverrides', type: 'string', default: '{}',
+    label: '旧版能力选择', labelEn: 'Legacy capability selections',
+    description: '旧配置迁移输入；新规则由能力工作台分别保存可用性与说明方式。',
+    descriptionEn: 'Migration input for older settings. The workbench saves availability and disclosure separately in the policy.' },
+  { key: 'capabilityStatistics', type: 'string',
+    default: '{"enabled":false,"windowSize":100,"minimumSamples":10,"fullThreshold":0.5}',
+    label: '能力统计设置', labelEn: 'Capability statistics settings',
+    description: '独立采集使用统计，并设置样本窗口、最低样本数和完整披露阈值；关闭或不可用时保留手动基线。',
+    descriptionEn: 'Collect usage statistics independently and set the sample window, minimum samples and full-disclosure threshold. Disabled or unavailable statistics preserve the manual baseline.' },
+  { key: 'capabilityProfiles', type: 'string', default: '{"schema":"ptc-capability-profiles/v1","profiles":[]}',
+    label: '保存的能力配置', labelEn: 'Saved capability configurations',
+    description: '在能力工作台命名保存、导入导出和切换配置；已有会话需要主动刷新。',
+    descriptionEn: 'Name, save, import, export and switch configurations in the capability workbench. Existing sessions require explicit refresh.' },
+  { key: 'capabilityBudgetBytes', type: 'integer', default: 16384, min: 1, max: Number.MAX_SAFE_INTEGER,
+    label: '完整说明预算 (UTF-8 bytes)', labelEn: 'Full contract budget (UTF-8 bytes)',
+    description: '显式 full 可以超出此预算；不截断调用契约。', descriptionEn: 'Explicit full selections may exceed this budget; calling contracts are never truncated.' },
+  { key: 'capabilityDirectoryBytes', type: 'integer', default: 2048, min: 512, max: Number.MAX_SAFE_INTEGER,
+    label: '能力导航预算 (UTF-8 bytes)', labelEn: 'Capability navigation budget (UTF-8 bytes)', description: '', descriptionEn: '' },
+  { key: 'capabilityRecoveryBytes', type: 'integer', default: 8192, min: 1, max: Number.MAX_SAFE_INTEGER,
+    label: '压缩后说明恢复预算 (UTF-8 bytes)', labelEn: 'Description recovery budget (UTF-8 bytes)', description: '', descriptionEn: '' },
+  { key: 'modelPreviewTokens', type: 'integer', default: 4096, min: 1, max: Number.MAX_SAFE_INTEGER,
+    label: '模型结果预览预算 (estimated tokens)', labelEn: 'Model result preview budget (estimated tokens)',
+    description: '选用模型侧预览时复用 DSH spill policy；完整内容需要宿主 spill store，程序值保持完整。',
+    descriptionEn: 'Uses DSH spill policy when model-facing previews are selected. Complete content requires a host spill store; program values remain complete.' },
   {
     key: 'legacyBindingSettings',
     type: 'boolean',
@@ -38,6 +88,15 @@ export const CONFIG_FIELDS = Object.freeze([
     description: '开启时使用增强工具卡片；关闭后使用 DSH 原生工具卡片。',
     descriptionEn: 'Uses enhanced tool cards when enabled and DSH native tool cards when disabled.',
   },
+  {
+    key: 'toolHoverPreviewEnabled',
+    type: 'boolean',
+    default: true,
+    label: '悬停预览执行内容',
+    labelEn: 'Preview execution content on hover',
+    description: '在增强执行卡片上停留或键盘聚焦时显示简短预览；滚动时自动隐藏。',
+    descriptionEn: 'Shows a quick preview on enhanced tool cards after hovering or keyboard focus; hides while scrolling.',
+  },
   {
     key: 'replViewEnabled',
     type: 'boolean',
@@ -53,8 +112,8 @@ export const CONFIG_FIELDS = Object.freeze([
     default: true,
     label: '显示 PTC Plus 快捷入口',
     labelEn: 'Show the PTC Plus shortcut',
-    description: '在输入框旁显示 PTC Plus 快捷入口：查看和启停全局绑定、编写新绑定，并直接打开插件设置窗口；隐藏后仍可使用 /binding 命令。',
-    descriptionEn: 'Shows the PTC Plus shortcut beside the composer: global binding access and toggles, authoring, and direct access to the plugin settings dialog. Hiding it keeps /binding commands available.',
+    description: '在输入框旁显示星光菜单：打开插件设置、刷新当前会话能力，并在全局绑定开启时查看、启停和编写绑定；隐藏后仍可使用斜杠命令。',
+    descriptionEn: 'Shows the sparkle menu beside the composer: open settings, refresh current-session capabilities, and manage or author global bindings when enabled. Hiding it does not remove slash commands.',
   },
   {
     key: 'autoDescribeRunCode',
@@ -156,6 +215,15 @@ export const CONFIG_FIELDS = Object.freeze([
     description: 'worker 重启后从 session journal 重建可恢复的 REPL 状态。',
     descriptionEn: 'Rebuilds recoverable REPL state from the session journal after a worker restart.',
   },
+  {
+    key: 'officialReplPriority',
+    type: 'boolean',
+    default: false,
+    label: '官方 REPL 模式优先',
+    labelEn: 'Prioritize the official REPL mode',
+    description: '检测到官方持久 REPL 模式时由官方运行时接管 PTC 会话执行；PTC Plus 让出 run_code 及其进程内会话状态语义，关闭时始终由 PTC Plus 接管。',
+    descriptionEn: 'Lets the official runtime own PTC session execution when the official persistent REPL mode is active; PTC Plus then leaves run_code and its in-process session-state semantics to DSH. Disabled keeps PTC Plus in charge.',
+  },
   {
     key: 'tipsEnabled',
     type: 'boolean',
@@ -296,12 +364,6 @@ export const CONFIG_GROUPS = Object.freeze([
     labelEn: 'Plugin switch',
     fields: Object.freeze(['enabled']),
   },
-  {
-    key: 'calls',
-    label: '调用容错',
-    labelEn: 'Tool call tolerance',
-    fields: Object.freeze(['autoDescribeRunCode', 'canonicalizeToolCalls']),
-  },
   {
     key: 'syntax',
     label: 'REPL 语法',
@@ -314,7 +376,7 @@ export const CONFIG_GROUPS = Object.freeze([
     key: 'recovery',
     label: '状态与恢复',
     labelEn: 'State and recovery',
-    fields: Object.freeze(['durableReplay', 'tipsEnabled', 'tipCooldownMessages', 'tipEscalationFailures']),
+    fields: Object.freeze(['durableReplay', 'officialReplPriority', 'tipsEnabled', 'tipCooldownMessages', 'tipEscalationFailures']),
   },
   {
     key: 'extensions',
@@ -322,11 +384,17 @@ export const CONFIG_GROUPS = Object.freeze([
     labelEn: 'Tool extensions',
     fields: Object.freeze(['userBindingsEnabled', 'cordisToolsEnabled']),
   },
+  {
+    key: 'calls',
+    label: '调用容错',
+    labelEn: 'Tool call tolerance',
+    fields: Object.freeze(['autoDescribeRunCode', 'canonicalizeToolCalls']),
+  },
   {
     key: 'interface',
     label: '界面显示',
     labelEn: 'Interface display',
-    fields: Object.freeze(['enhancedToolView', 'replViewEnabled', 'bindingAuthorButtonVisible']),
+    fields: Object.freeze(['enhancedToolView', 'toolHoverPreviewEnabled', 'replViewEnabled', 'bindingAuthorButtonVisible']),
   },
   {
     key: 'limits',
@@ -344,8 +412,19 @@ export const CONFIG_GROUPS = Object.freeze([
       'maxValueBigIntDigits',
     ]),
   },
+  { key: 'capabilities', label: '能力与上下文', labelEn: 'Capabilities and context',
+    fields: Object.freeze(['capabilityContextEnabled', 'capabilityManagementEnabled', 'capabilityBaseline', 'capabilityOverrides',
+      'capabilityStatistics', 'capabilityPolicy', 'capabilityRecoveryEnabled', 'modelPreviewEnabled', 'capabilityProfiles', 'capabilityBudgetBytes', 'capabilityDirectoryBytes', 'capabilityRecoveryBytes', 'modelPreviewTokens']) },
 ])
 
+/** Functional modules share the same section order across every settings entry. */
+export const CONFIG_MODULES = Object.freeze([
+  { key: 'workspace', label: '核心工作区', labelEn: 'Core workspace', groups: Object.freeze(['syntax', 'recovery']) },
+  { key: 'extensions', label: '扩展与容错', labelEn: 'Extensions and tolerance', groups: Object.freeze(['extensions', 'calls']) },
+  { key: 'presentation', label: '界面与资源', labelEn: 'Interface and resources', groups: Object.freeze(['interface', 'limits']) },
+  { key: 'experimental', label: '实验性', labelEn: 'Experimental', groups: Object.freeze(['capabilities']) },
+].map(Object.freeze))
+
 /** Resolved defaults, derived once from the field definitions. */
 export const CONFIG_DEFAULTS = Object.freeze(
   Object.fromEntries(CONFIG_FIELDS.map(field => [field.key, field.default])),

package/internal/direct-surface-owner.js

@@ -3,7 +3,6 @@ import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { validateJsonSchemaValue } from '@deepseek-ai/dsh-tools'
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
 import { canonicalizeToolCallStream } from './tool-call-canonicalizer.js'
-import { editRunCodeSchema } from './rejected-cell-editor.js'
 import { sessionRuntimeContexts } from './runtime-contexts.js'
 import { projectProgramSdk } from './sdk-projection.js'
 import { EDIT_RUN_CODE } from './edit-transport-owner.js'
@@ -16,11 +15,12 @@ import {
 } from './run-code-description.js'
 import { userBindingsConfiguredContext } from './user-bindings.js'
 import { BINDING_AUTHORING_SDK } from './user-binding-authoring.js'
+import { executionPolicies } from './binding-update-policy.js'
 
-const RUN_CODE_TOOL_DESCRIPTION = 'Evaluate the next TypeScript cell in this session-bound persistent REPL, reusing earlier top-level bindings. Use `code` for the async-function body and `description` for its short UI summary. Successful image-bearing subtool results are attached after the cell.'
-const RUN_CODE_CODE_DESCRIPTION = 'Code for the next REPL cell, parsed as the body of an async TypeScript function.'
+const RUN_CODE_TOOL_DESCRIPTION = 'Evaluate the next TypeScript cell in this session-bound persistent REPL, reusing earlier top-level bindings. Use `code` for the cell and `description` for its short UI summary. Successful image-bearing subtool results are attached after the cell.'
+const RUN_CODE_CODE_DESCRIPTION = 'Code for the next PTC TypeScript cell, following the selected language conventions.'
 const RUN_CODE_DESCRIPTION_DESCRIPTION = 'Short active-voice summary of what this cell does, 5-10 words (shown in the UI).'
-const CODE_TRANSPORT_INSTRUCTION = '`run_code` and `edit_run_code` are the only tools callable directly. Call every native tool declared by the SDK from inside a program.'
+const CODE_TRANSPORT_INSTRUCTION = '`run_code` is the only tool callable directly. Call `tools.edit_run_code` and other SDK tools from inside a program. An accepted edit runs after the current cell finishes.'
 const PTC_COLLAPSE_SECTION_NAMES = Object.freeze(['tools:ptc-only', 'tools:code-only'])
 const INVALID_TOOL_JSON_FAILURE = Object.freeze({
   code: 'MALFORMED_RESPONSE',
@@ -53,19 +53,20 @@ function adaptRunCodeSchema(tool) {
   }
 }
 
-function capabilitySdk(nativeSdk, userBindingsEnabled) {
-  return `${projectProgramSdk(nativeSdk)}
+function capabilitySdk(nativeSdk, userBindingsEnabled, languageSemantics) {
+  return `${projectProgramSdk(nativeSdk, { languageSemantics })}
 
 ## PTC Plus program capabilities
 
-Discover program APIs without calling them. \`tree()\` lists namespaces and members; \`inspect()\` describes selected \`namespace.member\` symbols. \`find()\` matches case-insensitive symbols or contiguous words, separating CamelCase and punctuation. Use short queries such as \`"read"\`; if none match, shorten the query or check \`tree()\`. Missing metadata is unknown.
+Discover program APIs without calling them. \`search({query})\` retrieves whole indexed API descriptions by English/Chinese words; its UTF-8 JSON byte budget includes the envelope, with a continuation cursor and inspect references for oversized entries. \`tree()\` lists namespaces and members; \`find()\` matches case-insensitive symbols or contiguous words, separating CamelCase and punctuation; \`inspect()\` returns selected \`namespace.member\` symbols with an item-count budget. Missing metadata is unknown.
 
 \`\`\`ts
-declare class CapabilityExplorationError extends Error { readonly operation: "tree" | "find" | "inspect" }
+declare class CapabilityExplorationError extends Error { readonly operation: "tree" | "find" | "inspect" | "search" }
 declare const capabilities: {
   tree(): Promise<Array<{ namespace: string; members: string[] }>>
   find(query: string): Promise<Array<{ symbol: string; description?: string; completeness: string; effect: string; replay: string }>>
   inspect(args?: { symbols?: string[]; budget?: number }): Promise<{ symbols: unknown[]; omitted: number; unknown: string[]; budget: number }>
+  search(args: { query: string; budgetBytes?: number; limit?: number; cursor?: string }): Promise<{ matches: Array<{ symbol: string; owner: unknown; contract: unknown }>; oversized: Array<{ symbol: string; requiredBytes: number; inspect: { symbols: string[]; budget: number } }>; total: number; remaining: number; cursor: string | null; budgetBytes: number; usedBytes: number; unit: "utf8-json-bytes" }>
 }
 \`\`\`${userBindingsEnabled ? `\n${BINDING_AUTHORING_SDK}` : ''}`
 }
@@ -118,16 +119,8 @@ function presentationState(assembly) {
   const collapse = PTC_COLLAPSE_SECTION_NAMES
     .map(name => assembly?.sections?.find(section => section?.name === name))
     .find(section => section !== undefined)
-  if (collapse !== undefined) {
-    const presentation = typeof collapse.text === 'string' && collapse.text.trim().length > 0
-      ? 'ptc'
-      : 'both'
-    return { presentation, ownerProven: true, collapseSectionName: collapse.name }
-  }
-  const presentation = tools.every(tool => tool?.name === RUN_CODE || tool?.name === EDIT_RUN_CODE)
-    ? 'ptc'
-    : 'both'
-  return { presentation, ownerProven: false, collapseSectionName: undefined }
+  return { presentation: 'ptc', ownerProven: collapse !== undefined,
+    collapseSectionName: collapse?.name }
 }
 
 async function* bindCallPolicies(source, policy, calls) {
@@ -465,6 +458,7 @@ export function createDirectSurfaceOwner({
   userBindingsForAgent = async () => undefined,
   setAgentPresentation = async () => {},
   sessionLogView,
+  capabilityEnvironment,
 }) {
   // Composition is anchored to Agent identity because DSH selects presentation
   // once per composed agent. Request signals bind the exact assembly to stream
@@ -478,6 +472,7 @@ export function createDirectSurfaceOwner({
   let disposed = false
   let currentCanonicalizeToolCalls = canonicalizeToolCalls
   let currentAutoDescribeRunCode = runtimeConfig.autoDescribeRunCode
+  let currentLanguageSemantics = executionPolicies(runtimeConfig).languageSemantics
   const tipConfig = {
     enabled: runtimeConfig.tipsEnabled,
     cooldownMessages: runtimeConfig.tipCooldownMessages,
@@ -563,6 +558,7 @@ export function createDirectSurfaceOwner({
 
   return Object.freeze({
     reconfigure(nextConfig) {
+      currentLanguageSemantics = executionPolicies(nextConfig).languageSemantics
       currentCanonicalizeToolCalls = nextConfig.canonicalizeToolCalls
       currentAutoDescribeRunCode = nextConfig.autoDescribeRunCode
       cordisRecovery.reconfigure(nextConfig.cordisToolsEnabled)
@@ -571,8 +567,11 @@ export function createDirectSurfaceOwner({
       tipConfig.escalationFailures = nextConfig.tipEscalationFailures
     },
     async assemble(initialAssembly, context, next) {
+      // Settings observes Host-owned catalogs without preparing a session environment.
+      if (context?.ptcPlusCapabilityObservation === true) return next()
       // Keep schema projection and later execution on one configuration snapshot.
       const autoDescribeRunCode = currentAutoDescribeRunCode
+      const languageSemantics = currentLanguageSemantics
       const agent = context?.agent
       const id = sessionId(agent)
       const requestOwner = id === undefined ? undefined : sessionOwner(id)
@@ -625,13 +624,14 @@ export function createDirectSurfaceOwner({
       if (!isCurrent()) return assembly
       const sessionPtc = presentation !== 'native' && id !== undefined
       const sessionPtcProjection = presentation === 'ptc' && id !== undefined
+      if (sessionPtc) await capabilityEnvironment?.prepare(agent, assembly.sections)
       const userBindings = sessionPtc ? await userBindingsForAgent(agent) : undefined
       if (!isCurrent()) return assembly
       const runCode = tools.find(tool => tool?.name === RUN_CODE)
-      let directTools = tools
+      let directTools = sessionPtc ? capabilityEnvironment?.visibleSchemas(agent, tools) ?? tools : tools
       if (sessionPtcProjection) {
         editTransport.ensureInstalled(agent)
-        directTools = [adaptRunCodeSchema(runCode), editRunCodeSchema()]
+        directTools = [adaptRunCodeSchema(runCode)]
       }
       const runtimeContexts = sessionPtc
         ? sessionRuntimeContexts(agent, tipConfig, {
@@ -650,9 +650,10 @@ export function createDirectSurfaceOwner({
         && assembly.sections.some(section => section?.name === 'tools:sdk'
           || (sessionPtcProjection && section?.name === completedState.collapseSectionName))
       const sections = projectsSections
-        ? assembly.sections.map(section => {
+        ? (capabilityEnvironment?.projectSections(agent, assembly.sections) ?? assembly.sections).map(section => {
             if (section?.name === 'tools:sdk') {
-              return { ...section, text: capabilitySdk(section.text, userBindings !== undefined) }
+              return { ...section, text: capabilitySdk(capabilityEnvironment?.sdk(agent, section.text) ?? section.text,
+                userBindings !== undefined, languageSemantics) }
             }
             if (sessionPtcProjection && section?.name === completedState.collapseSectionName) {
               return { ...section, text: CODE_TRANSPORT_INSTRUCTION }
@@ -662,7 +663,7 @@ export function createDirectSurfaceOwner({
         : assembly.sections
       if (id !== undefined) {
         const nativeSchemas = presentation === 'ptc'
-          ? new Map(toolSchemasForAgent(agent)
+          ? new Map((capabilityEnvironment?.visibleSchemas(agent, toolSchemasForAgent(agent)) ?? toolSchemasForAgent(agent))
             .filter(schema => typeof schema?.name === 'string'
               && schema.name !== RUN_CODE && schema.name !== EDIT_RUN_CODE)
             .map(schema => [schema.name, schema]))
@@ -706,20 +707,17 @@ export function createDirectSurfaceOwner({
       return bindCallPolicies(recovered, policy, policy.owner.calls)
     },
     executionRejection(exec) {
-      if (exec.name === EDIT_RUN_CODE && exec.parent !== undefined) {
-        return rejection(`tool ${EDIT_RUN_CODE} is only callable directly in PTC mode; call native tools from inside run_code`)
-      }
       const policy = dispatchPolicy(exec)
       if (exec.name === EDIT_RUN_CODE) {
-        return policy?.presentation === 'ptc'
+        return exec.parent !== undefined
           ? undefined
-          : rejection(`tool ${EDIT_RUN_CODE} is not declared for this request`)
+          : rejection(`tool ${EDIT_RUN_CODE} must be called through tools.${EDIT_RUN_CODE} inside run_code`)
       }
       if (exec.name === RUN_CODE || exec.parent !== undefined) {
         return undefined
       }
       if (policy?.presentation !== 'ptc') return undefined
-      return rejection(`tool ${exec.name} is not a direct PTC tool; use run_code or edit_run_code directly, and call native tools from inside run_code`)
+      return rejection(`tool ${exec.name} is not a direct PTC tool; use run_code directly, and call SDK tools from inside run_code`)
     },
     executionArguments(exec) {
       const policy = dispatchPolicy(exec)

package/internal/dynamic-environment-runtime.js

@@ -54,7 +54,7 @@ const asBindings = value => {
 
 /** Native reference operations over compiler-proved lexical and object frames. */
 export function createDynamicEnvironmentRuntime({
-  importModule = (source, options) => import(source, options),
+  importModule: defaultImportModule = (source, options) => import(source, options),
   intrinsicEval = defaultIntrinsics.intrinsicEval, realmFunction = defaultIntrinsics.realmFunction, globalObject = defaultIntrinsics.globalObject,
   errors, reflect = defaultIntrinsics.reflect, object, interfaceOwner, resolveAmbient = programAmbientResolver,
 } = {}) {
@@ -173,7 +173,7 @@ export function createDynamicEnvironmentRuntime({
 
   function environment({ frames = [], varFrame = new internal.Map(), strict = false, origin, lexicalContext = {},
     getThis = () => globalObject, getNewTarget = () => undefined, allowNewTarget = false,
-    ambient = ambientReference, createVar, declareVars, nativeAwait = false } = {}) {
+    ambient = ambientReference, createVar, declareVars, nativeAwait = false, importModule = defaultImportModule } = {}) {
     varFrame = asBindings(varFrame)
     const capturedFrames = []
     for (let index = 0; index < frames.length; index++) {
@@ -268,19 +268,19 @@ export function createDynamicEnvironmentRuntime({
           internal.copyArray(captured, rootIndex, captured.length, combined)
           internal.copyArray(frames, boundary, frames.length, combined)
         }
-        return environment({ frames: combined,
+        return environment({ importModule, frames: combined,
           varFrame, strict: nextStrict, getThis, getNewTarget, allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin, lexicalContext })
       },
       awaitActivation() {
         const local = new internal.Map()
-        return environment({ frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'lexical', bindings: local }]), varFrame: local,
+        return environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'lexical', bindings: local }]), varFrame: local,
           strict, getThis, getNewTarget, allowNewTarget, ambient, nativeAwait: true, origin, lexicalContext })
       },
       activation(bindings, nextGetThis = getThis, nextGetNewTarget = getNewTarget, nextStrict = strict, ownFunction = true, selfBindings) {
         bindings = asBindings(bindings)
         const activationFrames = [{ kind: 'lexical', bindings }]
         if (selfBindings !== undefined) internal.appendArray(activationFrames, { kind: 'self', bindings: asBindings(selfBindings) })
-        return environment({ frames: internal.copyArray(frames, 0, frames.length, activationFrames), varFrame: bindings,
+        return environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, activationFrames), varFrame: bindings,
           strict: nextStrict, getThis: nextGetThis, getNewTarget: nextGetNewTarget, allowNewTarget: ownFunction || allowNewTarget, ambient, origin,
           lexicalContext: ownFunction ? { privateReferences: lexicalContext.privateReferences } : lexicalContext })
       },
@@ -294,7 +294,7 @@ export function createDynamicEnvironmentRuntime({
           }
           const parameterFrames = [{ kind: 'lexical', bindings }]
           if (selfBindings !== undefined) internal.appendArray(parameterFrames, { kind: 'self', bindings: asBindings(selfBindings) })
-          selected = environment({ frames: internal.copyArray(frames, 0, frames.length, parameterFrames), varFrame: bindings,
+          selected = environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, parameterFrames), varFrame: bindings,
             strict: nextStrict, getThis: nextGetThis, getNewTarget: nextGetNewTarget, allowNewTarget: ownFunction || allowNewTarget, ambient, origin, lexicalContext })
           internal.weakMapSet(parameterEnvironments, key, selected)
         }
@@ -309,15 +309,15 @@ export function createDynamicEnvironmentRuntime({
         } })
         return nativeCalls.registerCallableSourceTarget(adapter, fn)
       },
-      context(options) { return environment({ frames, varFrame, strict: options.strict ?? strict,
+      context(options) { return environment({ importModule, frames, varFrame, strict: options.strict ?? strict,
         getThis: options.getThis ?? getThis, getNewTarget: options.getNewTarget ?? getNewTarget,
         allowNewTarget: options.allowNewTarget ?? allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin,
         lexicalContext: { ...lexicalContext, ...options } }) },
-      at(nextOrigin) { return environment({ frames, varFrame, strict, getThis, getNewTarget,
+      at(nextOrigin) { return environment({ importModule, frames, varFrame, strict, getThis, getNewTarget,
         allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin: nextOrigin, lexicalContext }) },
       withObject(value) {
         if (value === null || value === undefined) throw new errors.TypeError('Cannot convert undefined or null to object')
-        return environment({ frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'object', object: object(value) }]),
+        return environment({ importModule, frames: internal.copyArray(frames, 0, frames.length, [{ kind: 'object', object: object(value) }]),
           varFrame, strict, getThis, getNewTarget, allowNewTarget, ambient, createVar, declareVars, nativeAwait, origin, lexicalContext })
       },
       declareEvalVars(names) {