@askdkc/dsh-cli 0.11.3

package/cordis.yml

@@ -0,0 +1,250 @@
+# dsh-tui interactive front door over the agent-spine bundle.
+# Run with: dsh --config cordis.yml (或 npm 安装后走 dsh plugin 机制)
+# Requires DEEPSEEK_API_KEY; a terminal TTY is mandatory.
+
+# The user-interaction service: hosts `ctx.userQuestions`, the seam behind
+# the model-facing ask_user_question tool. dsh-tui uses the legacy provider
+# API when present, otherwise the scoped user-questions/request waterfall;
+# the service must live at the root so the agent loop's tool execution can
+# reach it.
+- id: user-questions
+  name: '@deepseek-ai/dsh-user-questions'
+
+# The approval service (issue #49): the harness's sandbox escalation seam
+# (`sandbox_permissions: danger-full-access`) asks ApprovalService.request(),
+# which dispatches an `approval/request` waterfall; dsh-tui registers itself
+# as the interactive answerer (ApprovalStore + approval panel). Without this
+# row the waterfall has no service and fail-closes to 'unavailable'. Policy
+# expression mirrors the profile cordis.patch.yml row exactly (verified by
+# scripts/verify-cordis-approval.mjs): ask everywhere except
+# danger-full-access (nothing needs asking) and Windows (no sandbox — the
+# user's terminal trust model, matching every other terminal coding agent).
+- id: approval
+  name: '@deepseek-ai/dsh-user-approval'
+  config:
+    policy: !!js "process.platform === 'win32' ? 'never' : ((process.env.DSH_PERMISSION_MODE ?? 'workspace-write') === 'danger-full-access' ? 'never' : 'ask')"
+
+- id: dsh-tui-workspaces
+  name: 'dsh-cli/workspaces'
+
+- id: dsh-tui-command-trees
+  name: 'dsh-cli/command-trees'
+
+# Optional plugins declare editable settings sections here (issue #165);
+# storage, validation and writes remain owned by the dsh settings service.
+- id: dsh-tui-settings-sections
+  name: 'dsh-cli/settings-sections'
+
+- id: dsh-tui-scenes
+  name: 'dsh-cli/scenes'
+
+# Plugin-interop anchor (v0.15): unified grant store, runtime generation
+# id, Host Descriptor; later contract surfaces mount off this row's apply.
+- id: dsh-tui-plugin-host
+  name: 'dsh-cli/plugin-host'
+
+# Plugin-facing UI seams: managed dialogs, status-line contributions,
+# keyboard shortcuts, custom session-entry renderers, and runtime themes
+# (decision events are fired by the channel and need no row).
+- id: dsh-tui-extensions
+  name: 'dsh-cli/extensions'
+
+- id: dsh-tui
+  name: 'dsh-cli'
+  # Entry-level only: orders/rebinds optional extension services on reload;
+  # dsh-tui does not hard-inject them at code level, so stale profiles degrade
+  # to static themes and inert extension surfaces instead of deadlocking boot.
+  inject: [agents, tuiWorkspaces, tuiScenes, tuiDialogs, tuiStatus, tuiShortcuts, tuiRenderers, tuiThemes]
+  config:
+    provider: deepseek-official
+    # Alt-screen fullscreen 布局: 应用内鼠标选区（选择即复制, OSC 52 +
+    # wl-copy/xclip/xsel 兜底）、滚轮滚动、双击选词/三击选行。false 则退回
+    # inline 渲染, 鼠标交给终端模拟器原生选择。
+    fullscreen: true
+    # 在支持的终端预览图片；/settings 可关闭，重启生效。
+    terminalImages: true
+    # 回复中的 ```mermaid 代码块画成字符图；false 保留源码。/settings 可实时改。
+    # mermaidDiagrams: true
+    # Reasoning effort applied to every request, validated against the live
+    # route's adapter levels. An unlisted level falls back to the adapter
+    # default; this wins over the persisted /effort choice and seeds the
+    # startup header/statusline.
+    effort: max
+    # Shift+Tab 会话模式循环（数组顺序即循环顺序；缺省为下面三档）。
+    # 每档可声明 plan（计划模式开/关）、sandbox（read-only/
+    # workspace-write/danger-full-access）、approval（ask/never）三个
+    # 原子的任意子集；未声明的原子不动。首档（index 0）为无标记基态。
+    # modes:
+    #   - id: default
+    #     plan: false
+    #     sandbox: workspace-write
+    #     approval: ask
+    #   - id: plan
+    #     plan: true
+    #     sandbox: read-only
+    #     approval: ask
+    #   - id: full
+    #     plan: false
+    #     sandbox: danger-full-access
+    #     approval: never
+    #  feeds the chosen session id through this env var (see
+    #  src/sessionHistory.ts for the launcher contract).
+    sessionId: !!js process.env.DSH_TUI_RESUME_SESSION ?? undefined
+    workspace: !!js process.env.DSH_TUI_WORKSPACE_TARGET ?? undefined
+
+# The DeepSeek adapter. Shipped default: full thinking at max effort.
+# rc.6 schema key is `apiKeyEnv` (a credential-ref env var NAME, default
+# DEEPSEEK_API_KEY), not `apiKey`; the old snapshot's `apiKey` key is
+# dropped by the loader and would never take effect.
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKeyEnv: 'DEEPSEEK_API_KEY'
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    thinking: enabled
+    reasoningEffort: max
+
+# Managed child-process groups for the bash executor.
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: !!js process.cwd()
+    timeoutMs: 60000
+
+# Filesystem service: `@` completion lists the session cwd through it, and
+# the model-facing fs tools resolve relative paths from the process cwd.
+- id: fs
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+# Read/write/edit policy loads before the model-facing filesystem tools so
+# writes and edits require an observed file (DSH's own fs policy gate).
+- id: fs-policy
+  name: '@deepseek-ai/dsh-fs-observation-policy'
+
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+# The todo_write tool replaces the logged whole list (DSH's todo tool).
+# allowParallelInProgress is REQUIRED (no schema default) — a bare mount
+# fails validation. True matches the official dsh-base bundle value.
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+
+# Subagents: the registry service, then the spawn/fork backends and the
+# delegation tools (max depth 1 keeps the TUI's tool cards shallow). The
+# core `dsh-subagent` service MUST be mounted before any provider.
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: subagent-spawn
+  name: '@deepseek-ai/dsh-subagent-spawn-in-process'
+  config:
+    providerName: spawn
+
+- id: subagent-fork
+  name: '@deepseek-ai/dsh-subagent-fork-in-process'
+  config:
+    providerName: fork
+
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+    toolName: subagent
+    backgroundMode: continuable
+    maxDepth: 1
+
+- id: tool-subagent-fork
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: fork
+    toolName: subagent_fork
+    backgroundMode: continuable
+    maxDepth: 1
+
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    persona: !!js process.env.DSH_TUI_PERSONA ?? 'You are a coding agent.'
+    # Workspace context (AGENTS.md injection) at the standard 64KB cap;
+    # task tools stay at their DSH defaults (on).
+    workspaceContext:
+      maxBytes: 65536
+    # Skills on: the spine mounts the local skill provider (discovers
+    # SKILL.md catalogs under ~/.dsh, ~/.agents and project roots) plus the
+    # model-facing skill catalog/load tools.
+    skills:
+      enabled: true
+    # Persisted goal stack: mounts the goal domain service + the model-facing
+    # goal tool; /goal (command-goal below) needs the service present.
+    goals: {}
+
+# Human-command registry: plan-mode's /plan and command-goal's /goal register
+# here; the TUI merges them into its slash menu and dispatches through the
+# registry (logs command/run + command/done). Must mount before the commands.
+- id: commands
+  name: '@deepseek-ai/dsh-commands'
+
+# Plan mode: the plan:policy prompt section, the /plan command and the
+# model-facing plan/exit tools (DSH's plan seam). `section` is REQUIRED and
+# non-empty — a bare mount fails validation and rolls the whole tree back.
+- id: plan-mode
+  name: '@deepseek-ai/dsh-plan-mode'
+  config:
+    section: |
+      You are in plan mode. Explore and design before presenting the
+      complete plan through exit_plan_mode.
+
+# /goal — set or view the goal for a long-running task (needs the goal
+# domain service mounted by agent-spine's `goals` config above).
+- id: command-goal
+  name: '@deepseek-ai/dsh-command-goal'
+
+# Working line plugin: folds the session stream into the `workingActivity`
+# session projection (≥0.5.0), which the TUI reads as its working-status
+# line; activity/status events are never persisted.
+# Mounted through dsh-cli's `./working-activity`
+# re-export (not the bare `dsh-working-activity` name) so the row resolves
+# from install layouts that never link transitive dependencies into the
+# boot anchor's node_modules — pnpm's isolated profile layout, issue #60.
+- id: working-activity
+  name: 'dsh-cli/working-activity'
+  config:
+    publish: false
+    publishIntervalMs: 500
+
+# Durable session log (DSH's own persistence seam): /resume and rewind both
+# rely on this backend writing every session/event. Root defaults under the
+# user home so sessions survive across terminals (Windows: USERPROFILE).
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: !!js process.env.DSH_TUI_SESSION_ROOT ?? (process.env.USERPROFILE ?? process.env.HOME) + '/.dsh-tui/sessions'
+
+# Read-only session lineage — the subagent service's /agents listing reads it.
+- id: session-query
+  name: '@deepseek-ai/dsh-session-query'
+
+- id: session-checkpoints
+  name: '@deepseek-ai/dsh-session-checkpoint-policy'
+
+# Token accounting + manual session compaction (/compact).
+- id: token-meter
+  name: '@deepseek-ai/dsh-token-meter'
+
+- id: compact
+  name: '@deepseek-ai/dsh-compaction-basic'
+  config:
+    # DeepSeek advertises a 1M context window, so the 80% default threshold
+    # would never make manual /compact useful. Default 20% (200k tokens)
+    # with a 5% retained tail; both are overridable for tests and must keep
+    # retainRatio < thresholdRatio (BasicCompactConfig validates this).
+    thresholdRatio: !!js parseFloat(process.env.DSH_TUI_COMPACT_RATIO ?? '0.2')
+    retainRatio: !!js parseFloat(process.env.DSH_TUI_COMPACT_RETAIN ?? '0.05')

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