martty 0.2.11

package/lib/client-run.js

@@ -0,0 +1,379 @@
+/**
+ * Evaluate a Cordis `code.client` function body on the TUI client tree.
+ *
+ * Same closure convention as the web runner: the source is an async function
+ * body that returns a plugin. Open services include `tuiTheme`, `tuiSlots`,
+ * `acpSessionConfig`, `acpSessionPlan`, `acpSessionStats`, and lifecycle-owned `timer`; `host.call` reaches this
+ * Package's Host half.
+ * No React, browser slots, TTY, or raw Host service names.
+ */
+
+const ALLOWED_INJECT = new Set([
+  'tuiTheme',
+  'tuiSlots',
+  'tuiCommands',
+  'tuiOverlay',
+  'acpSessionConfig',
+  'acpSessionPlan',
+  'acpSessionStats',
+  'timer',
+])
+
+const THEME_TEACHING =
+  'TUI Client Theme is ctx.tuiTheme, not ctx.theme. '
+  + 'register a complete 18-token palette with tuiTheme.register({ id, label, dark, light }) '
+  + 'inside one Theme Plugin; /theme loads or replaces that whole Plugin. '
+  + 'Token names are closed #RRGGBB keys, not CSS variables.'
+
+const SLOT_TEACHING =
+  'TUI shell slots are ctx.tuiSlots, not browser ctx.slots. '
+  + 'Inspect tuiSlots.list(), then use tuiSlots.inject(name, () => tuiSlots.register('
+  + '{ name, id }, nodes)).'
+
+/**
+ * @param {string} clientCode
+ * @param {{ pluginId?: string, tuiTheme?: object, tuiSlots?: object, tuiCommands?: object, tuiOverlay?: object, acpSessionConfig?: object, acpSessionPlan?: object, acpSessionStats?: object, timer?: object, invoke?: Function }} env
+ * @returns {Promise<{ waitingFor: string[], dispose: () => void }>}
+ */
+export async function applyClientHalf(clientCode, env) {
+  if (typeof clientCode !== 'string' || clientCode.trim().length === 0) {
+    throw new Error('TUI Client half is empty')
+  }
+  let plugin
+  try {
+    const factory = new Function(
+      'React',
+      'styles',
+      'host',
+      'harness',
+      'require',
+      'process',
+      'Buffer',
+      'setTimeout',
+      'setInterval',
+      `return (async () => {\n${clientCode}\n})()`,
+    )
+    plugin = await factory(
+      reactTrap,
+      stylesTrap,
+      hostFor(env),
+      harnessTrap,
+      requireTrap,
+      processTrap,
+      bufferTrap,
+      timerGlobalTrap,
+      timerGlobalTrap,
+    )
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(
+        `TUI Client half failed to parse: ${error.message}\n`
+        + 'The Client half is plain JavaScript (no JSX, no TypeScript).',
+      )
+    }
+    throw error
+  }
+  const evaluated = normalizePlugin(plugin)
+  const inject = evaluated.inject ?? []
+  for (const name of inject) {
+    if (name === 'theme') {
+      throw new Error(THEME_TEACHING)
+    }
+    if (name === 'slots') {
+      throw new Error(SLOT_TEACHING)
+    }
+    if (!ALLOWED_INJECT.has(name)) {
+      throw new Error(
+        `TUI Client inject "${name}" is not open. Open services: tuiTheme, tuiSlots, tuiCommands, tuiOverlay, acpSessionConfig, acpSessionPlan, acpSessionStats, timer.`,
+      )
+    }
+  }
+  const waitingFor = inject.filter((name) => env[name] === undefined)
+  if (waitingFor.length > 0) return { waitingFor, dispose() {} }
+
+  const owned = new Set()
+  const own = (dispose) => {
+    if (typeof dispose !== 'function') return dispose
+    let active = true
+    const release = () => {
+      if (!active) return
+      active = false
+      owned.delete(release)
+      return dispose()
+    }
+    owned.add(release)
+    return release
+  }
+  const ctx = restrictedCtx(env, own, new Set(inject))
+  const result = await evaluated.apply(ctx)
+  if (typeof result === 'function' && !owned.has(result)) own(result)
+  return {
+    waitingFor: [],
+    dispose() {
+      for (const release of [...owned].reverse()) release()
+    },
+  }
+}
+
+function normalizePlugin(value) {
+  if (typeof value === 'function') {
+    return { inject: [], apply: value }
+  }
+  if (value !== null && typeof value === 'object' && typeof value.apply === 'function') {
+    const inject = Array.isArray(value.inject) ? value.inject.map(String) : []
+    return { inject, apply: value.apply.bind(value) }
+  }
+  throw new Error(
+    'TUI Client half must return a plugin object `{ inject, apply }` or an apply function. '
+    + THEME_TEACHING,
+  )
+}
+
+function restrictedCtx(env, own, inject) {
+  const sourceTheme = env.tuiTheme
+  const sourceSlots = env.tuiSlots
+  const sourceCommands = env.tuiCommands
+  const sourceOverlay = env.tuiOverlay
+  const sourceSessionConfig = env.acpSessionConfig
+  const sourceSessionPlan = env.acpSessionPlan
+  const sourceSessionStats = env.acpSessionStats
+  const sourceTimer = env.timer
+  const tuiTheme = sourceTheme === undefined
+    ? undefined
+    : {
+        register(palette, options) {
+          const register = typeof env.pluginId === 'string'
+            && typeof sourceTheme.registerOwned === 'function'
+            ? sourceTheme.registerOwned.bind(sourceTheme, env.pluginId)
+            : sourceTheme.register.bind(sourceTheme)
+          const registration = register(palette, options)
+          const dispose = own(
+            typeof registration?.dispose === 'function'
+              ? registration.dispose.bind(registration)
+              : registration,
+          )
+          if (typeof dispose !== 'function') return dispose
+          dispose.dispose = dispose
+          if (typeof registration?.update === 'function') {
+            dispose.update = (patch) => registration.update(patch)
+          }
+          return dispose
+        },
+      }
+  const tuiSlots = sourceSlots === undefined
+    ? undefined
+    : {
+        inject(name, callback) {
+          return own(sourceSlots.inject(name, callback))
+        },
+        register(options, nodes) {
+          const panel = sourceSlots.register(options, nodes)
+          const dispose = own(() => panel.dispose())
+          return {
+            update(nextNodes) {
+              return panel.update(nextNodes)
+            },
+            dispose,
+          }
+        },
+        list() {
+          return sourceSlots.list()
+        },
+      }
+  const tuiCommands = sourceCommands === undefined
+    ? undefined
+    : {
+        register(options, handler) {
+          return own(sourceCommands.register(options, handler))
+        },
+        list() {
+          return sourceCommands.list()
+        },
+      }
+  const tuiOverlay = sourceOverlay === undefined
+    ? undefined
+    : {
+        openSlider(options, handlers) {
+          const controller = sourceOverlay.openSlider(options, handlers)
+          const close = own(() => controller.close())
+          return { close }
+        },
+        openView(options, handlers) {
+          const controller = sourceOverlay.openView(options, handlers)
+          const close = own(() => controller.close())
+          return { close }
+        },
+        active() {
+          return sourceOverlay.active()
+        },
+      }
+  const acpSessionConfig = sourceSessionConfig === undefined
+    ? undefined
+    : {
+        list() {
+          return sourceSessionConfig.list()
+        },
+        current(id) {
+          return sourceSessionConfig.current(id)
+        },
+        byCategory(category) {
+          return sourceSessionConfig.byCategory(category)
+        },
+        transaction(selector) {
+          const transaction = sourceSessionConfig.transaction(selector)
+          own(() => transaction.rollback())
+          return transaction
+        },
+        set(id, value) {
+          return sourceSessionConfig.set(id, value)
+        },
+        subscribe(listener) {
+          return own(sourceSessionConfig.subscribe(listener))
+        },
+      }
+  const acpSessionPlan = sourceSessionPlan === undefined
+    ? undefined
+    : {
+        list() {
+          return sourceSessionPlan.list()
+        },
+        current() {
+          return sourceSessionPlan.current()
+        },
+        subscribe(listener) {
+          return own(sourceSessionPlan.subscribe(listener))
+        },
+      }
+  const acpSessionStats = sourceSessionStats === undefined
+    ? undefined
+    : {
+        current() {
+          return sourceSessionStats.current()
+        },
+        subscribe(listener) {
+          return own(sourceSessionStats.subscribe(listener))
+        },
+      }
+  const timer = sourceTimer === undefined || !inject.has('timer')
+    ? undefined
+    : {
+        interval(callback, delay) {
+          return own(sourceTimer.interval(callback, delay))
+        },
+        timeout(callback, delay) {
+          return own(sourceTimer.timeout(callback, delay))
+        },
+      }
+  return {
+    tuiTheme,
+    tuiSlots,
+    tuiCommands,
+    tuiOverlay,
+    acpSessionConfig,
+    acpSessionPlan,
+    acpSessionStats,
+    timer,
+    interval: timer?.interval,
+    timeout: timer?.timeout,
+    get(name) {
+      if (name === 'tuiTheme') return tuiTheme
+      if (name === 'tuiSlots') return tuiSlots
+      if (name === 'tuiCommands') return tuiCommands
+      if (name === 'tuiOverlay') return tuiOverlay
+      if (name === 'acpSessionConfig') return acpSessionConfig
+      if (name === 'acpSessionPlan') return acpSessionPlan
+      if (name === 'acpSessionStats') return acpSessionStats
+      if (name === 'timer') return timer
+      return undefined
+    },
+    effect(fn) {
+      return typeof fn === 'function' ? own(fn()) : undefined
+    },
+    on() {
+      throw new Error('TUI Client events are not open yet')
+    },
+    provide() {
+      throw new Error('TUI Client halves cannot provide services')
+    },
+    plugin() {
+      throw new Error('mount TUI contributions with tuiTheme/tuiSlots, not ctx.plugin')
+    },
+  }
+}
+
+function reactTrap() {
+  throw new Error(
+    'React is not available on the TUI Client. Use tuiTheme palettes or tuiSlots TuiNode trees.',
+  )
+}
+
+const stylesTrap = {
+  insert() {
+    throw new Error('styles.insert is a browser Client symbol. TUI palettes use tuiTheme.register.')
+  },
+}
+
+function hostFor(env) {
+  return {
+    call(method, args = null) {
+      if (typeof env.invoke !== 'function') {
+        return Promise.reject(new Error('host.call is unavailable without an active TUI Cordis Host run'))
+      }
+      return Promise.resolve().then(() => env.invoke(method, args))
+    },
+  }
+}
+
+function timerGlobalTrap() {
+  throw new Error(
+    "timer globals are unavailable in dynamic TUI plugins; declare inject: ['timer'] and use ctx.interval/timeout",
+  )
+}
+
+/** Create lifecycle-neutral timer operations; the dynamic Context owns each returned disposer. */
+export function createClientTimer() {
+  return {
+    interval(callback, delay) {
+      assertTimerArgs('interval', callback, delay)
+      const handle = globalThis.setInterval(callback, delay)
+      return () => globalThis.clearInterval(handle)
+    },
+    timeout(callback, delay) {
+      assertTimerArgs('timeout', callback, delay)
+      const handle = globalThis.setTimeout(callback, delay)
+      return () => globalThis.clearTimeout(handle)
+    },
+  }
+}
+
+function assertTimerArgs(name, callback, delay) {
+  if (typeof callback !== 'function') throw new Error(`ctx.${name}: callback must be a function`)
+  if (typeof delay !== 'number' || !Number.isFinite(delay) || delay < 0) {
+    throw new Error(`ctx.${name}: delay must be a non-negative finite number`)
+  }
+}
+
+const harnessTrap = new Proxy({}, {
+  get(_target, prop) {
+    throw new Error(
+      `harness.${String(prop)} belongs to the HOST half (code.host). `
+      + 'Register Package-private methods there with harness.handle; call them here with host.call.',
+    )
+  },
+})
+
+function requireTrap() {
+  throw new Error('modules cannot be imported in a dynamic Client half')
+}
+
+const processTrap = new Proxy({}, {
+  get() {
+    throw new Error('process is not available in a TUI Client half')
+  },
+})
+
+const bufferTrap = new Proxy({}, {
+  get() {
+    throw new Error('Buffer is not available in a TUI Client half')
+  },
+})

package/lib/cordis-protocol.js

@@ -0,0 +1,51 @@
+/** ACP extension contract for DSH Cordis client capabilities. */
+
+export const CORDIS_PROTOCOL = 0
+
+export const CORDIS_CAPABILITY = Object.freeze({ protocol: CORDIS_PROTOCOL })
+
+export const CORDIS_METHODS = Object.freeze({
+  inspectSync: '_dsh/cordis/inspect/sync',
+  inspectResolve: '_dsh/cordis/inspect/resolve',
+  inspectQuery: '_dsh/cordis/inspect/query',
+  inspectQueryResolved: '_dsh/cordis/inspect/query-resolved',
+  runHost: '_dsh/cordis/run/host',
+  getClientCode: '_dsh/cordis/run/client-code',
+  resolveRequestRun: '_dsh/cordis/run/resolve',
+  requestRun: '_dsh/cordis/run/request',
+  requestRunResolved: '_dsh/cordis/run/request-resolved',
+  userRun: '_dsh/cordis/run/user',
+  settleUserRun: '_dsh/cordis/run/settle',
+  pluginInvoke: '_dsh/cordis/plugin/invoke',
+  pluginsList: '_dsh/cordis/plugins/list',
+  pluginStart: '_dsh/cordis/plugins/start',
+  pluginStop: '_dsh/cordis/plugins/stop',
+  pluginRetract: '_dsh/cordis/plugins/retract',
+  themeUpdate: '_dsh/cordis/tui/theme/update',
+  themeRemove: '_dsh/cordis/tui/theme/remove',
+  themeSelected: '_dsh/cordis/tui/theme/selected',
+  slotsUpdate: '_dsh/cordis/tui/slots/update',
+  commandsUpdate: '_dsh/cordis/tui/commands/update',
+  commandInvoke: '_dsh/cordis/tui/commands/invoke',
+  overlayUpdate: '_dsh/cordis/tui/overlay/update',
+  overlayEvent: '_dsh/cordis/tui/overlay/event',
+  sessionConfigSet: '_dsh/cordis/tui/session-config/set',
+})
+
+/**
+ * Read the negotiated DSH Cordis capability from an ACP initialize result.
+ * @param {unknown} result
+ * @returns {{ protocol: number } | null}
+ */
+export function readCordisCapability(result) {
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) return null
+  const capabilities = result.agentCapabilities
+  if (capabilities === null || typeof capabilities !== 'object' || Array.isArray(capabilities)) return null
+  const meta = capabilities._meta
+  if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) return null
+  const dsh = meta.dsh
+  if (dsh === null || typeof dsh !== 'object' || Array.isArray(dsh)) return null
+  const cordis = dsh.cordis
+  if (cordis === null || typeof cordis !== 'object' || Array.isArray(cordis)) return null
+  return cordis.protocol === CORDIS_PROTOCOL ? { protocol: CORDIS_PROTOCOL } : null
+}

package/lib/creator-overlay.js

@@ -0,0 +1,77 @@
+/**
+ * Add TUI plugin authoring guidance to the shipped Creator preset without
+ * copying or modifying that preset's composition.
+ */
+
+import { readFileSync } from 'node:fs'
+
+export const name = 'tui-creator-overlay'
+export const inject = ['agentPresets', 'skills', 'systemPrompt', 'loader']
+
+const SKILL_NAME = 'tui-plugin-development'
+const ROUTING_PROMPT = `# Dynamic TUI Plugin routing
+
+Load cordis-plugin-development for every dynamic Plugin; it owns the common Plugin, Package, lifecycle, approval, Host, RPC, and repair model.
+
+- When any requested behavior belongs to the TUI — terminal themes or backgrounds, native TUI slots, local TUI commands, native overlays, or current ACP Session options — also load tui-plugin-development. Its TUI Provider guidance overrides generic browser UI assumptions only for that half.
+- Browser/Web-only work needs no TUI companion. A mixed Plugin uses the generic skill for common, Host, and Web behavior and the TUI skill for its terminal behavior. Do not translate a TUI request into Web Slots or add Host code unless the requested behavior owns Host data.`
+
+const skillDocument = readFileSync(
+  new URL('../skills/tui-plugin-development/SKILL.md', import.meta.url),
+  'utf8',
+)
+const skillFrontmatter = skillDocument.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
+if (!skillFrontmatter) {
+  throw new Error('tui-creator-overlay: TUI skill frontmatter is unavailable')
+}
+const skillDescription = skillFrontmatter[1]
+  .match(/^description:\s*(.+)$/m)?.[1]
+  ?.trim()
+if (!skillDescription) {
+  throw new Error('tui-creator-overlay: TUI skill description is unavailable')
+}
+const skillContent = skillDocument.slice(skillFrontmatter[0].length)
+
+/**
+ * @param {object} ctx
+ * @param {{ preset?: string }} [config]
+ */
+export async function apply(ctx, config = {}) {
+  const preset = config.preset ?? 'cordis'
+  if (typeof preset !== 'string' || preset.length === 0) {
+    throw new Error('tui-creator-overlay: preset must be a non-empty string')
+  }
+  const key = await ctx.agentPresets.standingKeyFor(preset)
+  const scopeModule = await ctx.loader.import('@deepseek-ai/dsh-scope')
+  if (typeof scopeModule?.createScope !== 'function') {
+    throw new Error('tui-creator-overlay: profile dsh-scope module is unavailable')
+  }
+  const { createScope } = scopeModule
+  const overlay = createScope(ctx, key)
+  try {
+    const skills = overlay.ctx.get('skills')
+    if (skills === undefined || typeof skills.register !== 'function') {
+      throw new Error('tui-creator-overlay: skills service is unavailable in the preset scope')
+    }
+    skills.register({
+      name: SKILL_NAME,
+      description: skillDescription,
+      source: 'martty/creator-overlay',
+      content: skillContent,
+      invocation: { modelInvocable: true, userInvocable: true },
+    })
+    const systemPrompt = overlay.ctx.get('systemPrompt')
+    if (systemPrompt === undefined || typeof systemPrompt.section !== 'function') {
+      throw new Error('tui-creator-overlay: systemPrompt service is unavailable in the preset scope')
+    }
+    systemPrompt.section({
+      name: 'tool:tui-cordis-routing',
+      order: 116,
+      text: ROUTING_PROMPT,
+    })
+    ctx.effect(() => () => overlay.dispose(), `tui-creator-overlay(${JSON.stringify(preset)})`)
+  } catch (error) {
+    await overlay.dispose()
+    throw error
+  }
+}

package/lib/demo-skin.js

@@ -0,0 +1,79 @@
+/**
+ * `--demo-skin` entry: mount gallery pack `ember` through `tuiTheme.register`,
+ * spawn the native TUI in `--demo` attach mode, and flush the Cordis TUI
+ * theme update with
+ * `activate: true`. Runnable as `node npm/lib/demo-skin.js`.
+ */
+
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import * as emberPlugin from './ember.js'
+import { JsonRpcLineTransport } from './jsonrpc-line-transport.js'
+import { nativeBinary, spawnPluginTui } from './spawn-tui.js'
+import * as themePlugin from './tui-theme.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const { version } = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'))
+
+function extraBinaryArgs(argv) {
+  const extra = ['--demo']
+  for (const arg of argv) {
+    if (arg === '--demo-skin' || arg === '--demo') continue
+    extra.push(arg)
+  }
+  return extra
+}
+
+/**
+ * Register ember, activate it, spawn the TUI, and serve the attach handshake.
+ * @param {string[]} [argv]
+ */
+export async function runDemoSkin(argv = process.argv.slice(2)) {
+  const { Context } = await import('@deepseek-ai/cordis')
+  const ctx = new Context()
+  await ctx.plugin(themePlugin)
+  await ctx.plugin(emberPlugin)
+  const theme = ctx.tuiTheme
+  ctx.tuiTheme.activate('ember')
+
+  const bin = process.env.DSH_TUI_BIN || nativeBinary()
+  const connection = await spawnPluginTui(bin, extraBinaryArgs(argv))
+  const { child } = connection
+  const transport = new JsonRpcLineTransport(connection.input, connection.output)
+
+  function notify(method, params) {
+    transport.notify(method, params)
+  }
+  theme.bindNotify(notify)
+
+  transport.onRequest(async (method) => {
+    switch (method) {
+      case 'initialize':
+        return { serverInfo: { name: 'dsh-tui-demo-skin', version } }
+      case 'session/prompt':
+        return { messageId: 'demo-skin' }
+      case 'shutdown':
+        return {}
+      default:
+        throw new Error(`unknown method: ${method}`)
+    }
+  })
+
+  transport.start()
+  connection.resume?.()
+
+  child.on('exit', (code) => {
+    process.exit(code === null ? 0 : code)
+  })
+  child.on('error', (err) => {
+    console.error(`dsh-tui demo-skin failed: ${err.message}`)
+    process.exit(1)
+  })
+}
+
+const isMain = process.argv[1] !== undefined
+  && path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1])
+if (isMain) {
+  await runDemoSkin(process.argv.slice(2))
+}

package/lib/ember.js

@@ -0,0 +1,20 @@
+/**
+ * Gallery palette pack `ember`. Registers complete dark/light token maps.
+ * Does not activate: `--demo-skin` calls `tuiTheme.activate('ember')`.
+ * `inject = ['tuiTheme']`: sibling profile row, not `ctx.plugin` inside the runner.
+ */
+
+import { readFileSync } from 'node:fs'
+
+const emberPalette = JSON.parse(
+  readFileSync(new URL('./palettes/ember.json', import.meta.url), 'utf8'),
+)
+
+export const name = 'tui-theme-ember'
+export const inject = ['tuiTheme']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.tuiTheme.register(emberPalette, { activate: false }))
+}
+
+export { emberPalette }