@deepseek-harness-tui/dsh-tui 0.8.1 → 0.8.3

package/README.md

@@ -13,6 +13,12 @@
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
   <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
   <img alt="官方收录" src="https://img.shields.io/badge/DeepSeek%20Harness%20官方公众号-收录-brightgreen">
+  <a href="https://github.com/ccch1mneyyy/dsh-TUI/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ccch1mneyyy/dsh-TUI?style=flat-square&color=4b6fff"></a>
+  <a href="https://www.npmjs.com/package/@deepseek-harness-tui/dsh-tui"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@deepseek-harness-tui/dsh-tui?style=flat-square&color=4b6fff"></a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/146168" title="GitHub Trending 日榜 #7 · TypeScript 口径"><img alt="Trendshift" src="https://trendshift.io/api/badge/trendshift/repositories/146168/daily?language=TypeScript"></a>
 </p>
 
 # dsh-TUI
@@ -87,8 +93,14 @@ sh install.sh
 已上架 VS Code Marketplace**）见
 [在 VS Code 中运行 dsh-TUI](docs/vscode.md)。
 
-TUI 启动后会在后台检查 npm 是否有新版本；发现更新时会提示，输入 `/update`
-即可自动更新并重启恢复当前会话。
+TUI 启动后会在后台检查 npm 是否有新版本；发现更新时可输入 `/update`。
+`/update` 更新当前 `dsh-tui` profile 中的 runtime 并重启会话，它不会静默修改
+npm/pnpm 的全局安装。若通过全局 `dsh-tui` 命令启动且 Launcher 版本落后，
+0.8.3 起会给出精确的全局对齐命令，例如：
+
+```sh
+npm install -g @deepseek-harness-tui/dsh-tui@<profile-version>
+```
 
 旧版 `dsh-cc-tui` / `cc-tui` profile 的迁移命令与兼容数据说明见
 [安装与快速开始](docs/getting-started.md#从旧包迁移)。
@@ -100,7 +112,7 @@ TUI 启动后会在后台检查 npm 是否有新版本；发现更新时会提
 
 | 键 | 功能 |
 |---|---|
-| `Enter` | 发送（`Shift+Enter` 换行）；命令菜单打开时执行选中项 |
+| `Enter` | 发送（`Shift+Enter` 换行，无法上报修饰键时可用 `Ctrl+J`）；命令菜单打开时执行选中项 |
 | `Ctrl+C` | 中断当前回合；空闲时连按两次退出 |
 | `Esc` | 关闭命令/文件菜单；空闲双击清空输入；**空输入双击 = 时间回溯** |
 | `Ctrl+O` | 展开/收起详情（思考全文、工具参数与输出） |
@@ -143,12 +155,26 @@ macOS 自带 Terminal.app 会自行消费 `⌘` 快捷键，请继续使用 `Ctr
 |---|---|
 | 会话 | `/new` 新会话 · `/resume` 会话浏览器（搜索、预览、跨项目、折叠子 agent 运行） · `/rename` 重命名会话 · `/workspace resume|rename|open` 管理工作区 · `/clear` 清屏 · `/compact` 压缩 · `/export` 导出 Markdown · `/trace` 轨迹场景（亦可 `Ctrl+T`） |
 | 状态 | `/context` 已加载上下文明细 · `/status` 会话信息 · `/cost` token 用量 · `/doctor` 环境自检 · `/config` 配置来源 · `/init` 创建 AGENTS.md |
-| 模型 | `/model` 选择器 · `/thinking` 思考显示 · `/tokens` token 明细 · `/theme` 主题选择器 · `/lang` 中英界面切换 |
+| 模型 | `/model` 选择器 · `/thinking` 思考显示 · `/tokens` token 明细 · `/theme` 主题选择器 · `/lang` 中英界面切换（`/settings` 中亦可选择） |
 | 账号/策略 | `/provider` 添加模型提供方 · `/login` 凭证状态 · `/logout` 登出说明 · `/permissions` 权限说明 · `/add-dir` 文件策略范围 · `/hooks` · `/mcp` |
 | 技能 | `/audit` 代码审计 · `/bug` bug 报告 · `/review` 代码评审 · `/practice` 编程练习 · `/pr_comments` PR 评论 · `/release-notes` 发布说明 · `/vuln-check` 漏洞检查 |
 | 其它 | `/agents` 子代理列表 · `/update` 自动更新并重启 · `/vim` · `/terminal-setup` · `/connect` · `/help` · `/exit` |
 | 注册表 | `/plan` `/goal`（DSH 命令注册表插件，随插件自动并入 `/` 菜单） |
 
+## 插件生态
+
+想为 dsh-TUI 做插件/扩展？欢迎加入生态！
+
+- **接口与兼容性协定**：[终端交互生态插件准入规范与实施标准](https://github.com/T-Auto/dsh-ecosystem-spec)
+- **插件开发指南**：[`docs/plugins.md`](docs/plugins.md)（接缝、契约、规范与验证清单）
+- **生态组织**：[dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)（社区插件与模板的家）
+- **模板仓库**：[plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template)（从模板起步，5 分钟出一个插件）
+- **参考实现**：`dsh-working-activity`（实时工作状态行：TUI 槽位 + `activity/status` 会话事件双出口）
+
+核心仓库不迁移、社区插件独立成仓。组织只维护收录列表与准入规范，不对社区插件
+的功能、质量或安全作背书或担保；插件作者对自己的仓库保持完全所有权，并自行承担
+维护与安全责任。
+
 ## 文档
 
 | 主题 | 内容 |
@@ -256,18 +282,7 @@ pnpm smoke
 构建门禁。npm Git URL 安装通过 `prepare` 生成同一套运行时。渲染、问卷和工具卡
 改动还需运行对应回归脚本。
 
-## 插件生态
-
-想为 dsh-TUI 做插件/扩展？欢迎加入生态：
-
-- **插件开发指南**：[`docs/plugins.md`](docs/plugins.md)（接缝、契约、规范与验证清单）
-- **生态组织**：[dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)（社区插件与模板的家）
-- **模板仓库**：[plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template)（从模板起步，5 分钟出一个插件）
-- **参考实现**：`dsh-working-activity`（实时工作状态行：TUI 槽位 + `activity/status` 会话事件双出口）
 
-核心仓库不迁移、社区插件独立成仓。组织只维护收录列表与准入规范，不对社区插件
-的功能、质量或安全作背书或担保；插件作者对自己的仓库保持完全所有权，并自行承担
-维护与安全责任。
 
 ## 社区
 

package/bin/dsh-tui.js

@@ -30,6 +30,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { gt, valid } from 'semver'
 import { shellQuote } from '../lib/types/utils/shellQuote.js'
 import { detectLegacyEnv, RENAMED_ENV } from '../lib/types/utils/paths.js'
 
@@ -63,15 +64,32 @@ const MSG = {
     en: `[dsh-tui] Plugin install failed. Retry manually later:\n  dsh plugin --profile ${PROFILE} add -w ${PACKAGE}@${ownVersion}`,
     zh: `[dsh-tui] 插件安装失败。可稍后手工重试：\n  dsh plugin --profile ${PROFILE} add -w ${PACKAGE}@${ownVersion}`,
   },
-  versionMismatch: {
+  // Non-fatal skew comes in two directions and each needs its own repair:
+  // a profile NEWER than the launcher (typical after /update) must point at
+  // the global install, while a profile older only in patch must point back
+  // at the profile. The old generic message told forward-skew users to run
+  // /update again — an "Already up to date" loop.
+  profileOutdated: {
     en: (installed, own) =>
       `[dsh-tui] note: the profile is running v${installed} but this launcher is v${own}.\n` +
-      `  To update the profile: run /update inside the TUI, or:\n` +
-      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@latest`,
+      `  Align the profile to this launcher:\n` +
+      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${own}`,
     zh: (installed, own) =>
-      `[dsh-tui] 提示：profile 内运行的是 v${installed}，而启动器是 v${own}。\n` +
-      `  更新 profile：在 TUI 内执行 /update，或运行：\n` +
-      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@latest`,
+      `[dsh-tui] 提示：profile 内运行的是 v${installed}，启动器是 v${own}。\n` +
+      `  请把 profile 对齐到启动器版本：\n` +
+      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${own}`,
+  },
+  launcherOutdated: {
+    en: (installed, own) =>
+      `[dsh-tui] note: the profile is already v${installed}, but the global launcher is still v${own}.\n` +
+      `  Align the global dsh-tui launcher to the profile:\n` +
+      `  npm install -g ${PACKAGE}@${installed}\n` +
+      `  (if you installed it globally with pnpm: pnpm add -g ${PACKAGE}@${installed})`,
+    zh: (installed, own) =>
+      `[dsh-tui] 提示：profile 已是 v${installed}，但全局启动器仍是 v${own}。\n` +
+      `  请把全局 dsh-tui 启动器对齐到 profile 版本：\n` +
+      `  npm install -g ${PACKAGE}@${installed}\n` +
+      `  （如果你使用 pnpm 全局安装：pnpm add -g ${PACKAGE}@${installed}）`,
   },
   // Reverse skew (issue #183): the dsh CLI reads the bundle patch from the
   // FIRST copy found from its own install anchor — this globally installed
@@ -182,7 +200,19 @@ if (installedVersion === undefined) {
     console.error(MSG.profileOlderThanLauncher[lang](installedVersion, ownVersion))
     process.exit(1)
   }
-  console.error(MSG.versionMismatch[lang](installedVersion, ownVersion))
+
+  // Non-fatal skew: repair in the direction the versions actually moved.
+  // A profile NEWER than the launcher (e.g. right after /update) means the
+  // GLOBAL launcher is stale — never point those users back at /update.
+  // Exact versions only: @latest could skip past the alignment point if a
+  // newer release or a mirror dist-tag is in play.
+  const installedSemver = valid(installedVersion)
+  const ownSemver = valid(ownVersion)
+  if (installedSemver !== null && ownSemver !== null && gt(installedSemver, ownSemver)) {
+    console.error(MSG.launcherOutdated[lang](installedVersion, ownVersion))
+  } else {
+    console.error(MSG.profileOutdated[lang](installedVersion, ownVersion))
+  }
 }
 
 // --- 3. --resume 拦截 ---------------------------------------------------------
@@ -240,6 +270,12 @@ for (const oldName of detectLegacyEnv()) {
 }
 
 // --- 4. 启动 ------------------------------------------------------------------
+// Contract for the profile runtime: lets /update diagnose whether the
+// global dsh-tui launcher is older than the profile it just installed.
+// Not a one-shot marker — it must survive restarts so the runtime always
+// knows the launcher generation it boots under.
+process.env.DSH_TUI_LAUNCHER_VERSION = ownVersion
+
 const child = spawn(...cmd('dsh', ['--profile', PROFILE, ...args]), {
   stdio: 'inherit',
   env: process.env,

package/dsh-ecosystem-spec/protocols/profile-definitions.d.ts

@@ -0,0 +1,13 @@
+import type { ApiReference, ProtocolCatalog, ProtocolDefinition } from '@dsh-std/core'
+export { registerTuiContributionExtensions } from './tui-contributions.js'
+export * from './tui-channel.js'
+
+export const DECISION_EVENTS: Readonly<ApiReference & {
+  apiVersion: 'tui.dsh/v1alpha1'
+  kind: 'DecisionEvents'
+}>
+
+export const decisionEventsDefinition: ProtocolDefinition
+export const profileDefinitions: readonly ProtocolDefinition[]
+
+export function registerProfileProtocols(catalog: ProtocolCatalog): () => void

package/dsh-ecosystem-spec/protocols/profile-definitions.js

@@ -0,0 +1,59 @@
+/** dsh-TUI private protocol definitions evaluated by @dsh-std/core. */
+
+export { registerTuiContributionExtensions } from './tui-contributions.js'
+export * from './tui-channel.js'
+import { tuiChannelDefinition } from './tui-channel.js'
+
+export const DECISION_EVENTS = Object.freeze({
+  apiVersion: 'tui.dsh/v1alpha1',
+  kind: 'DecisionEvents',
+})
+
+function featureSupport(value, label) {
+  if (value === undefined) return Object.freeze({ features: Object.freeze([]) })
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} support spec must be an object`)
+  }
+  const unknown = Object.keys(value).filter(key => key !== 'features' && !key.startsWith('x-'))
+  if (unknown.length > 0) throw new TypeError(`${label} support spec contains unknown field ${JSON.stringify(unknown[0])}`)
+  if (value.features !== undefined && (!Array.isArray(value.features)
+    || value.features.some(feature => typeof feature !== 'string' || feature.trim() === ''))) {
+    throw new TypeError(`${label} support spec.features must be an array of non-empty strings`)
+  }
+  return Object.freeze({ features: Object.freeze([...(value.features ?? [])].sort()) })
+}
+
+function providerDefinition(reference, label) {
+  return Object.freeze({
+    ...reference,
+    validateRequirement(value) {
+      if (value !== undefined) throw new TypeError(`${label} requirement does not accept spec in manifest v0.15`)
+      return undefined
+    },
+    validateSupport(value) { return featureSupport(value, label) },
+    negotiate(input) {
+      const providers = [...new Set(input.supports.map(row => row.participant))].sort()
+      const issues = input.requirements.flatMap(row => providers.length === 0
+        ? [{
+            code: row.requirement.optional === true ? 'optional-support-missing' : 'required-support-missing',
+            severity: row.requirement.optional === true ? 'warning' : 'error',
+            participant: row.participant,
+            message: `${label} has no provider in this negotiation scope`,
+          }]
+        : [])
+      return { agreement: Object.freeze({ providers: Object.freeze(providers) }), issues: Object.freeze(issues) }
+    },
+  })
+}
+
+export const decisionEventsDefinition = providerDefinition(DECISION_EVENTS, 'DecisionEvents')
+
+export const profileDefinitions = Object.freeze([
+  decisionEventsDefinition,
+  tuiChannelDefinition,
+])
+
+export function registerProfileProtocols(catalog) {
+  const disposers = profileDefinitions.map(definition => catalog.register(definition))
+  return () => { for (const dispose of disposers.reverse()) dispose() }
+}

package/dsh-ecosystem-spec/protocols/tui-channel-http.d.ts

@@ -0,0 +1,15 @@
+export const TUI_CHANNEL_HTTP_API_VERSION: 'tui.dsh/v1alpha1'
+export const TUI_CHANNEL_HTTP_KIND: 'ChannelEndpoint'
+export const TUI_CHANNEL_HTTP_HEALTH_PATH: '/dsh-tui/v1/health'
+export const TUI_CHANNEL_HTTP_DESCRIPTOR_PATH: '/dsh-tui/v1/endpoint'
+export const TUI_CHANNEL_HTTP_WEBSOCKET_PATH: '/dsh-tui/v1/connection'
+
+export interface TuiChannelEndpointDescriptor {
+  readonly apiVersion: typeof TUI_CHANNEL_HTTP_API_VERSION
+  readonly kind: typeof TUI_CHANNEL_HTTP_KIND
+  readonly origin: string
+  readonly connection: typeof TUI_CHANNEL_HTTP_WEBSOCKET_PATH
+}
+
+export function createTuiChannelEndpointDescriptor(origin: string): TuiChannelEndpointDescriptor
+export function validateTuiChannelEndpointDescriptor(value: unknown): TuiChannelEndpointDescriptor

package/dsh-ecosystem-spec/protocols/tui-channel-http.js

@@ -0,0 +1,32 @@
+export const TUI_CHANNEL_HTTP_API_VERSION = 'tui.dsh/v1alpha1'
+export const TUI_CHANNEL_HTTP_KIND = 'ChannelEndpoint'
+export const TUI_CHANNEL_HTTP_HEALTH_PATH = '/dsh-tui/v1/health'
+export const TUI_CHANNEL_HTTP_DESCRIPTOR_PATH = '/dsh-tui/v1/endpoint'
+export const TUI_CHANNEL_HTTP_WEBSOCKET_PATH = '/dsh-tui/v1/connection'
+
+export function createTuiChannelEndpointDescriptor(origin) {
+  const normalized = new URL(origin)
+  if (normalized.protocol !== 'http:' && normalized.protocol !== 'https:') {
+    throw new TypeError('TUI Channel endpoint origin must use http or https')
+  }
+  normalized.pathname = '/'
+  normalized.search = ''
+  normalized.hash = ''
+  return Object.freeze({
+    apiVersion: TUI_CHANNEL_HTTP_API_VERSION,
+    kind: TUI_CHANNEL_HTTP_KIND,
+    origin: normalized.toString().replace(/\/$/u, ''),
+    connection: TUI_CHANNEL_HTTP_WEBSOCKET_PATH,
+  })
+}
+
+export function validateTuiChannelEndpointDescriptor(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new TypeError('TUI Channel endpoint descriptor must be an object')
+  if (value.apiVersion !== TUI_CHANNEL_HTTP_API_VERSION || value.kind !== TUI_CHANNEL_HTTP_KIND) {
+    throw new TypeError('TUI Channel endpoint descriptor version or kind is unsupported')
+  }
+  if (typeof value.origin !== 'string') throw new TypeError('TUI Channel endpoint origin must be a string')
+  createTuiChannelEndpointDescriptor(value.origin)
+  if (value.connection !== TUI_CHANNEL_HTTP_WEBSOCKET_PATH) throw new TypeError('TUI Channel endpoint connection path is unsupported')
+  return value
+}

package/dsh-ecosystem-spec/protocols/tui-channel.d.ts

@@ -0,0 +1,59 @@
+import type { ApiReference, ProtocolDefinition } from '@dsh-std/core'
+
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue }
+
+export const TUI_CHANNEL: Readonly<ApiReference & {
+  apiVersion: 'tui.dsh/v1alpha1'
+  kind: 'Channel'
+}>
+export const TUI_CHANNEL_WIRE_REVISION: 6
+export const TUI_CHANNEL_FEATURES: readonly string[]
+
+export interface TuiChannelRequirementSpec {
+  readonly wireRevision: number
+  readonly features: readonly string[]
+}
+export interface TuiChannelSupportSpec extends TuiChannelRequirementSpec {}
+
+export interface TuiChannelSnapshot {
+  readonly wireRevision: number
+  readonly channelId: string
+  readonly version: number
+  readonly state: Readonly<Record<string, JsonValue>>
+}
+
+export interface TuiChannelWorkspaceFlowChoice {
+  readonly id: string
+  readonly label: string
+  readonly description?: string
+  readonly badge?: string
+  readonly action: string
+  readonly input?: {
+    readonly action: string
+    readonly initialValue?: string
+    readonly placeholder?: string
+  }
+}
+
+export type TuiChannelWorkspaceFlowResult =
+  | { readonly kind: 'target'; readonly target: import('./tui-contributions.js').WorkspaceTarget }
+  | { readonly kind: 'choices'; readonly title: string; readonly choices: readonly TuiChannelWorkspaceFlowChoice[] }
+
+export type TuiChannelInput =
+  | { readonly operation: 'open'; readonly value: { readonly workspace?: string; readonly sessionId?: string; readonly options?: JsonValue } }
+  | { readonly operation: 'subscribe'; readonly value: { readonly channelId: string; readonly afterVersion: number } }
+  | { readonly operation: 'invoke'; readonly value: { readonly channelId: string; readonly method: string; readonly arguments: readonly JsonValue[] } }
+  | { readonly operation: 'close'; readonly value: { readonly channelId: string } }
+
+export interface TuiChannelInvokeOutput {
+  readonly value: JsonValue
+  readonly valueDefined?: boolean
+  readonly snapshot?: TuiChannelSnapshot
+}
+
+export const tuiChannelDefinition: ProtocolDefinition
+export function validateTuiChannelRequirement(value: unknown): TuiChannelRequirementSpec
+export function validateTuiChannelSupport(value: unknown): TuiChannelSupportSpec
+export function validateTuiChannelInput(operation: string, value: unknown): object
+export function validateTuiChannelSnapshot(value: unknown): TuiChannelSnapshot
+export function validateTuiChannelOutput(operation: string, value: unknown): object

package/dsh-ecosystem-spec/protocols/tui-channel.js

@@ -0,0 +1,166 @@
+import { defineCapabilityProtocol } from '@dsh-std/connection'
+
+export const TUI_CHANNEL = Object.freeze({
+  apiVersion: 'tui.dsh/v1alpha1',
+  kind: 'Channel',
+})
+
+export const TUI_CHANNEL_WIRE_REVISION = 6
+
+export const TUI_CHANNEL_FEATURES = Object.freeze([
+  'commands',
+  'credentials',
+  'diagnostics',
+  'files',
+  'models',
+  'modes',
+  'presets',
+  'presentation',
+  'provider-setup',
+  'scenes',
+  'session-history',
+  'session-input',
+  'session-lifecycle',
+  'session-state',
+  'settings',
+  'skills',
+  'subagents',
+  'trace',
+  'workspaces',
+])
+
+export const tuiChannelDefinition = defineCapabilityProtocol({
+  ...TUI_CHANNEL,
+  validateRequirement: validateTuiChannelRequirement,
+  validateSupport: validateTuiChannelSupport,
+})
+
+export function validateTuiChannelRequirement(value) {
+  const spec = exactRecord(value, ['wireRevision', 'features'], 'Channel requirement')
+  const wireRevision = positiveInteger(spec.wireRevision, 'Channel requirement.wireRevision')
+  const features = featureList(spec.features, 'Channel requirement.features')
+  return Object.freeze({ wireRevision, features })
+}
+
+export function validateTuiChannelSupport(value) {
+  const spec = exactRecord(value, ['wireRevision', 'features'], 'Channel support')
+  const wireRevision = positiveInteger(spec.wireRevision, 'Channel support.wireRevision')
+  const features = featureList(spec.features, 'Channel support.features')
+  return Object.freeze({ wireRevision, features })
+}
+
+export function validateTuiChannelInput(operation, value) {
+  switch (operation) {
+    case 'open': {
+      const input = exactRecord(value, ['workspace', 'sessionId', 'options'], 'Channel.open input')
+      optionalString(input.workspace, 'Channel.open input.workspace')
+      optionalString(input.sessionId, 'Channel.open input.sessionId')
+      if (input.options !== undefined) jsonValue(input.options, 'Channel.open input.options', new Set())
+      return input
+    }
+    case 'subscribe': {
+      const input = exactRecord(value, ['channelId', 'afterVersion'], 'Channel.subscribe input')
+      nonEmpty(input.channelId, 'Channel.subscribe input.channelId')
+      nonNegativeInteger(input.afterVersion, 'Channel.subscribe input.afterVersion')
+      return input
+    }
+    case 'invoke': {
+      const input = exactRecord(value, ['channelId', 'method', 'arguments'], 'Channel.invoke input')
+      nonEmpty(input.channelId, 'Channel.invoke input.channelId')
+      nonEmpty(input.method, 'Channel.invoke input.method')
+      if (!Array.isArray(input.arguments)) throw new TypeError('Channel.invoke input.arguments must be an array')
+      jsonValue(input.arguments, 'Channel.invoke input.arguments', new Set())
+      return input
+    }
+    case 'close': {
+      const input = exactRecord(value, ['channelId'], 'Channel.close input')
+      nonEmpty(input.channelId, 'Channel.close input.channelId')
+      return input
+    }
+    default:
+      throw new TypeError(`Channel operation ${JSON.stringify(operation)} is not defined`)
+  }
+}
+
+export function validateTuiChannelSnapshot(value) {
+  const snapshot = exactRecord(value, ['wireRevision', 'channelId', 'version', 'state'], 'Channel snapshot')
+  positiveInteger(snapshot.wireRevision, 'Channel snapshot.wireRevision')
+  nonEmpty(snapshot.channelId, 'Channel snapshot.channelId')
+  nonNegativeInteger(snapshot.version, 'Channel snapshot.version')
+  const state = exactRecord(snapshot.state, Object.keys(snapshot.state ?? {}), 'Channel snapshot.state')
+  jsonValue(state, 'Channel snapshot.state', new Set())
+  return snapshot
+}
+
+export function validateTuiChannelOutput(operation, value) {
+  if (operation === 'open' || operation === 'subscribe') return validateTuiChannelSnapshot(value)
+  if (operation === 'invoke') {
+    const output = exactRecord(value, ['value', 'valueDefined', 'snapshot'], 'Channel.invoke output')
+    jsonValue(output.value, 'Channel.invoke output.value', new Set())
+    if (output.valueDefined !== undefined && typeof output.valueDefined !== 'boolean') {
+      throw new TypeError('Channel.invoke output.valueDefined must be boolean')
+    }
+    if (output.snapshot !== undefined) validateTuiChannelSnapshot(output.snapshot)
+    return output
+  }
+  if (operation === 'close') {
+    const output = exactRecord(value, ['closed'], 'Channel.close output')
+    if (output.closed !== true) throw new TypeError('Channel.close output.closed must be true')
+    return output
+  }
+  throw new TypeError(`Channel operation ${JSON.stringify(operation)} is not defined`)
+}
+
+function exactRecord(value, allowed, label) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new TypeError(`${label} must be an object`)
+  const unknown = Object.keys(value).filter(key => !allowed.includes(key) && !key.startsWith('x-'))
+  if (unknown.length > 0) throw new TypeError(`${label} contains unknown field ${JSON.stringify(unknown[0])}`)
+  return value
+}
+
+function featureList(value, label) {
+  if (!Array.isArray(value) || value.length === 0) throw new TypeError(`${label} must be a non-empty array`)
+  const features = value.map((feature, index) => {
+    nonEmpty(feature, `${label}[${index}]`)
+    return feature
+  })
+  if (new Set(features).size !== features.length) throw new TypeError(`${label} contains duplicates`)
+  return Object.freeze([...features].sort())
+}
+
+function positiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${label} must be a positive integer`)
+  return value
+}
+
+function nonNegativeInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${label} must be a non-negative integer`)
+  return value
+}
+
+function nonEmpty(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new TypeError(`${label} must be a non-empty string`)
+}
+
+function optionalString(value, label) {
+  if (value !== undefined) nonEmpty(value, label)
+}
+
+function jsonValue(value, label, ancestors) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError(`${label} must contain only finite numbers`)
+    return
+  }
+  if (typeof value !== 'object') throw new TypeError(`${label} must be a JSON value`)
+  if (ancestors.has(value)) throw new TypeError(`${label} must not contain cycles`)
+  ancestors.add(value)
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) jsonValue(item, `${label}[${index}]`, ancestors)
+  } else {
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null) throw new TypeError(`${label} must contain only plain objects`)
+    for (const [key, item] of Object.entries(value)) jsonValue(item, `${label}.${key}`, ancestors)
+  }
+  ancestors.delete(value)
+}

package/dsh-ecosystem-spec/protocols/tui-contributions.d.ts

@@ -0,0 +1,42 @@
+import type { ApiReference } from '@dsh-std/core'
+import type { ManifestDefinitionCatalog, ManifestObjectDefinition } from '@dsh-std/manifest'
+
+export const API_VERSION: 'tui.dsh/v1alpha1'
+export const SETTINGS_SECTION: Readonly<ApiReference & { kind: 'SettingsSection' }>
+export const SCENE: Readonly<ApiReference & { kind: 'Scene' }>
+
+export type LocalizedText = Readonly<Record<string, string>>
+export type SettingsFieldKind = 'text' | 'number' | 'boolean' | 'select'
+export interface SettingsFieldOption { readonly value: string; readonly label: string; readonly titles?: LocalizedText }
+export interface SettingsFieldSpec {
+  readonly path: readonly string[]
+  readonly label: string
+  readonly titles?: LocalizedText
+  readonly hint?: string
+  readonly hintTitles?: LocalizedText
+  readonly kind: SettingsFieldKind
+  readonly options?: readonly SettingsFieldOption[]
+  readonly placeholder?: string
+  readonly secretRef?: string
+}
+export interface SettingsSectionSpec {
+  readonly namespace: string
+  readonly title: string
+  readonly titles?: LocalizedText
+  readonly fields: readonly SettingsFieldSpec[]
+}
+export interface SettingsSectionHandler {}
+
+export interface SceneSpec { readonly title?: string; readonly titles?: LocalizedText }
+export interface SceneHandler<Props = unknown, Result = unknown> {
+  readonly component: (props: Props) => Result
+}
+
+export const settingsSectionExtensionDefinition: ManifestObjectDefinition
+export const sceneExtensionDefinition: ManifestObjectDefinition
+export const contributionExtensionDefinitions: readonly ManifestObjectDefinition[]
+export function validateSettingsSectionSpec(value: unknown): Readonly<SettingsSectionSpec>
+export function validateSceneSpec(value: unknown): Readonly<SceneSpec>
+export function registerTuiContributionExtensions(catalog: ManifestDefinitionCatalog): () => void
+export function assertSettingsSectionHandler(value: unknown): asserts value is SettingsSectionHandler
+export function assertSceneHandler(value: unknown): asserts value is SceneHandler