@chatcode/chatcode-cli 3.0.2 → 3.0.3

package/lib/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/lib/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/lib/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/lib/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/lib/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/lib/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/lib/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

package/lib/dsh-ecosystem-spec/protocols/tui-contributions.js

@@ -0,0 +1,143 @@
+/** dsh-TUI private, lifecycle-owned manifest contribution definitions. */
+
+export const API_VERSION = 'tui.dsh/v1alpha1'
+
+export const SETTINGS_SECTION = Object.freeze({
+  apiVersion: API_VERSION,
+  kind: 'SettingsSection',
+})
+
+export const SCENE = Object.freeze({
+  apiVersion: API_VERSION,
+  kind: 'Scene',
+})
+
+export const settingsSectionExtensionDefinition = Object.freeze({
+  ...SETTINGS_SECTION,
+  validateMetadata(metadata) {
+    contributionName(metadata?.name, 'SettingsSection metadata.name')
+  },
+  validateSpec: validateSettingsSectionSpec,
+})
+
+export function validateSettingsSectionSpec(value) {
+  const spec = exactRecord(value, ['namespace', 'title', 'titles', 'fields'], 'SettingsSection content')
+  contributionName(spec.namespace, 'SettingsSection content.namespace')
+  nonEmpty(spec.title, 'SettingsSection content.title')
+  localized(spec.titles, 'SettingsSection content.titles')
+  if (!Array.isArray(spec.fields)) throw new TypeError('SettingsSection content.fields must be an array')
+  return Object.freeze({
+    namespace: spec.namespace,
+    title: spec.title,
+    ...(spec.titles === undefined ? {} : { titles: freezeRecord(spec.titles) }),
+    fields: Object.freeze(spec.fields.map((field, index) => validateSettingsField(field, index))),
+  })
+}
+
+export const sceneExtensionDefinition = Object.freeze({
+  ...SCENE,
+  validateMetadata(metadata) {
+    contributionName(metadata?.name, 'Scene metadata.name')
+  },
+  validateSpec: validateSceneSpec,
+})
+
+export function validateSceneSpec(value) {
+  const spec = exactRecord(value, ['title', 'titles'], 'Scene content')
+  if (spec.title !== undefined) nonEmpty(spec.title, 'Scene content.title')
+  localized(spec.titles, 'Scene content.titles')
+  return Object.freeze({
+    ...(spec.title === undefined ? {} : { title: spec.title }),
+    ...(spec.titles === undefined ? {} : { titles: freezeRecord(spec.titles) }),
+  })
+}
+
+export const contributionExtensionDefinitions = Object.freeze([
+  settingsSectionExtensionDefinition,
+  sceneExtensionDefinition,
+])
+
+export function registerTuiContributionExtensions(catalog) {
+  const disposers = contributionExtensionDefinitions.map(definition => catalog.registerExtension(definition))
+  return () => { for (const dispose of disposers.reverse()) dispose() }
+}
+
+export function assertSettingsSectionHandler(value) {
+  runtimeObject(value, 'SettingsSection handler')
+}
+
+export function assertSceneHandler(value) {
+  const handler = runtimeObject(value, 'Scene handler')
+  if (typeof handler.component !== 'function') throw new TypeError('Scene handler.component must be a function')
+}
+
+function validateSettingsField(value, index) {
+  const label = `SettingsSection spec.fields[${index}]`
+  const field = exactRecord(value, [
+    'path', 'label', 'titles', 'hint', 'hintTitles', 'kind', 'options', 'placeholder', 'secretRef',
+  ], label)
+  if (!Array.isArray(field.path) || field.path.length === 0
+    || field.path.some(segment => typeof segment !== 'string' || segment.length === 0)) {
+    throw new TypeError(`${label}.path must be a non-empty string array`)
+  }
+  nonEmpty(field.label, `${label}.label`)
+  localized(field.titles, `${label}.titles`)
+  if (field.hint !== undefined) nonEmpty(field.hint, `${label}.hint`)
+  localized(field.hintTitles, `${label}.hintTitles`)
+  if (!['text', 'number', 'boolean', 'select'].includes(field.kind)) {
+    throw new TypeError(`${label}.kind is invalid`)
+  }
+  if (field.placeholder !== undefined && typeof field.placeholder !== 'string') {
+    throw new TypeError(`${label}.placeholder must be a string`)
+  }
+  if (field.secretRef !== undefined) nonEmpty(field.secretRef, `${label}.secretRef`)
+  if (field.options !== undefined) {
+    if (!Array.isArray(field.options)) throw new TypeError(`${label}.options must be an array`)
+    for (const [optionIndex, valueOption] of field.options.entries()) {
+      const option = exactRecord(valueOption, ['value', 'label', 'titles'], `${label}.options[${optionIndex}]`)
+      nonEmpty(option.value, `${label}.options[${optionIndex}].value`)
+      nonEmpty(option.label, `${label}.options[${optionIndex}].label`)
+      localized(option.titles, `${label}.options[${optionIndex}].titles`)
+    }
+  }
+  return Object.freeze(structuredClone(field))
+}
+
+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 runtimeObject(value, label) {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`)
+  }
+  return value
+}
+
+function contributionName(value, label) {
+  if (typeof value !== 'string' || !/^[a-z][a-z0-9_-]*$/u.test(value)) {
+    throw new TypeError(`${label} is invalid`)
+  }
+}
+
+function nonEmpty(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new TypeError(`${label} must be a non-empty string`)
+}
+
+function localized(value, label) {
+  if (value === undefined) return
+  const record = exactRecord(value, Object.keys(value), label)
+  for (const [locale, text] of Object.entries(record)) {
+    if (locale.trim() === '') throw new TypeError(`${label} contains an empty locale`)
+    nonEmpty(text, `${label}.${locale}`)
+  }
+}
+
+function freezeRecord(value) {
+  return Object.freeze({ ...value })
+}

package/lib/dsh-ecosystem-spec/registry/README.md

@@ -0,0 +1,14 @@
+# dsh-TUI Admission Protocol Profile
+
+[`registry-0.15.json`](registry-0.15.json) 不是全局协议注册表。它描述本 TUI admission profile 使用的 definition 集合：
+
+- `imports` 引用固定 dsh-std revision 已提供的 definitions；
+- `definitions` 只收录 dsh-TUI 私有 definitions。
+
+导入条目不复制 dsh-std 的 schema 或 contract 正文。Community v0.15 的 `Command`、`LocalStorage`、`MessageObserver`、Presentation 与 Workspace 定义分别由 `@dsh-std/command`、`@dsh-std/storage`、`@dsh-std/messages`、`@dsh-std/presentation` 与 `@dsh-std/workspace` 注册。
+
+本地 definition 的 contract profile 使用 SHA-256 固定。修改 profile 内容必须更新 digest，并按兼容性决定保留坐标或发布新 `apiVersion`。digest 只证明字节一致，不证明发布者身份。
+
+`tui.dsh/*` 是 dsh-TUI 私有 namespace。私有 definition 与公共 definition 一样注册到 dsh-std `ProtocolCatalog`；目录收录本身不产生 live support。
+
+权限目录仍是 TUI authorization policy 的输入。permission grant 与 protocol support 分开判断，安装 definition 不自动授权操作。

package/lib/dsh-ecosystem-spec/registry/contracts/decision-events-v1alpha1.json

@@ -0,0 +1,13 @@
+{
+  "name":"tui.decision-events","version":"v1alpha1","kind":"capability",
+  "coordinates":{"apiVersion":"tui.dsh/v1alpha1","kind":"DecisionEvents"},
+  "caller":"authorized TUI decision-point dispatcher",
+  "permissions":["session.input.intercept","session.rewind.intercept","session.switch.intercept","session.compact.intercept"],
+  "operations":[{"name":"decide","input":{"event":"private decision envelope"},"output":{"decision":"event-point-defined decision or no-opinion"}}],
+  "errors":["INTERCEPT_PERMISSION_NOT_GRANTED","DECISION_STALE","DECISION_BUDGET_EXCEEDED","INVALID_DECISION"],
+  "concurrency":"one decision chain is serialized; independent decision points may run concurrently",
+  "timeout":"the dispatcher applies an explicit per-handler and total decision budget",
+  "cleanup":"subscriptions are owned by an activation scope and removed on deactivate or grant revocation",
+  "privacyClass":"sensitive",
+  "securityBoundary":false
+}

package/lib/dsh-ecosystem-spec/registry/contracts/scene-v1alpha1.json

@@ -0,0 +1,13 @@
+{
+  "name":"tui.scene","version":"v1alpha1","kind":"extension",
+  "coordinates":{"apiVersion":"tui.dsh/v1alpha1","kind":"Scene"},
+  "caller":"trusted in-process dsh-TUI scene shell",
+  "permissions":[],
+  "operations":["open","close","render"],
+  "errors":["SCENE_INVALID","SCENE_CONFLICT","RENDERER_INCOMPATIBLE"],
+  "concurrency":"one scene may own the full-screen surface at a time",
+  "timeout":"scene operations are local; domain calls made by a scene retain their own deadlines",
+  "cleanup":"an open scene closes when its owning facet deactivates",
+  "privacyClass":"sensitive",
+  "securityBoundary":false
+}

package/lib/dsh-ecosystem-spec/registry/contracts/settings-section-v1alpha1.json

@@ -0,0 +1,13 @@
+{
+  "name":"tui.settings-section","version":"v1alpha1","kind":"extension",
+  "coordinates":{"apiVersion":"tui.dsh/v1alpha1","kind":"SettingsSection"},
+  "caller":"dsh-TUI settings contribution binder",
+  "permissions":[],
+  "operations":["render"],
+  "errors":["SECTION_INVALID","NAMESPACE_CONFLICT","NAMESPACE_UNAVAILABLE"],
+  "concurrency":"one active section owns each settings namespace",
+  "timeout":"not applicable to declarative rendering; writes use the settings protocol deadline",
+  "cleanup":"removing a section removes only UI metadata and preserves settings and credentials",
+  "privacyClass":"public",
+  "securityBoundary":false
+}

package/lib/dsh-ecosystem-spec/registry/contracts/tui-channel-v1alpha1.json

@@ -0,0 +1,30 @@
+{
+  "name": "tui.channel",
+  "version": "v1alpha1",
+  "coordinates": {
+    "apiVersion": "tui.dsh/v1alpha1",
+    "kind": "Channel"
+  },
+  "kind": "capability",
+  "caller": "a negotiated TUI endpoint",
+  "permissions": [],
+  "operations": [
+    {"name": "open", "input": "workspace/session selector", "output": "complete channel snapshot"},
+    {"name": "subscribe", "input": "channel id and last observed version", "output": "snapshot progress stream"},
+    {"name": "invoke", "input": "channel method and JSON arguments", "output": "method progress, JSON result and optional snapshot"},
+    {"name": "close", "input": "channel id", "output": "closed acknowledgement"}
+  ],
+  "wireRevision": 6,
+  "features": [
+    "commands", "credentials", "diagnostics", "files", "models", "modes",
+    "presets", "presentation", "provider-setup", "scenes", "session-history", "session-input",
+    "session-lifecycle", "session-state", "settings", "skills", "subagents",
+    "trace", "workspaces"
+  ],
+  "errors": ["CHANNEL_NOT_FOUND", "FEATURE_UNAVAILABLE", "INVALID_ARGUMENT", "PERMISSION_DENIED", "REVISION_MISMATCH", "PROVIDER_FAILURE"],
+  "concurrency": "state mutations are serialized per channel; independent read operations may run concurrently",
+  "timeout": "the caller supplies connection invocation cancellation; subscriptions remain open until cancelled or closed",
+  "cleanup": "connection close or facet deactivate releases subscriptions, uploads and channel attachments",
+  "privacyClass": "sensitive",
+  "securityBoundary": false
+}

package/lib/dsh-ecosystem-spec/registry/contracts/workspace-provider-v1alpha1.json

@@ -0,0 +1,6 @@
+{
+  "status": "superseded",
+  "coordinates": {"apiVersion": "workspace.dsh/v1alpha1", "kind": "WorkspaceProvider"},
+  "package": "@dsh-std/workspace",
+  "proposal": "vendor/dsh-std/docs/proposals/workspace.zh.md"
+}