martty 0.2.11

package/lib/runner.js

@@ -0,0 +1,94 @@
+/**
+ * Host-side TUI launcher.
+ *
+ * The dsh profile keeps the Base and ACP server on its Host Cordis tree. This
+ * plugin starts a separate Node process for the TUI Client Cordis tree and
+ * connects the two processes through the Client process's standard ACP
+ * stdin/stdout. Separate inherited descriptors carry the user's TTY.
+ */
+
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-tui-runner'
+export const inject = ['loader', 'acpServer', 'cmdlineArgs', 'appExit']
+
+const clientEntry = fileURLToPath(new URL('./client-process.js', import.meta.url))
+const requireFromTui = createRequire(import.meta.url)
+
+function ownAcpBridge() {
+  const specifier = '@openma/deepseek-harness-acp/bridge'
+  try {
+    return requireFromTui.resolve(specifier)
+  } catch {
+    // A source-linked package may rely on the active profile's installation.
+    return specifier
+  }
+}
+
+function appExitOf(ctx) {
+  return ctx.root?.get?.('appExit') ?? ctx.get?.('appExit') ?? ctx.appExit
+}
+
+/** @param {object} ctx */
+export async function apply(ctx) {
+  const bridge = await ctx.loader.import(ownAcpBridge())
+  if (typeof bridge.nodeAcpStream !== 'function') {
+    throw new Error('dsh-tui: ACP bridge does not export nodeAcpStream')
+  }
+  const child = spawn(
+    process.execPath,
+    [clientEntry, ...ctx.cmdlineArgs.get()],
+    {
+      // ACP owns the Client process's stdin/stdout. Its fd 3/4 retain the
+      // user's terminal for the Rust painter spawned inside that process.
+      stdio: ['pipe', 'pipe', 'inherit', process.stdin, process.stdout],
+      env: process.env,
+    },
+  )
+  const agentToClient = child.stdin
+  const clientToAgent = child.stdout
+  agentToClient?.on?.('error', () => {})
+  clientToAgent?.on?.('error', () => {})
+
+  let connection
+  let released = false
+  let exitRequested = false
+  const requestExit = (code) => {
+    if (exitRequested) return
+    exitRequested = true
+    appExitOf(ctx)?.(code)
+  }
+  const release = async () => {
+    if (released) return
+    released = true
+    process.off('exit', onProcessExit)
+    if (child.exitCode === null) child.kill('SIGTERM')
+    await connection?.dispose?.()
+  }
+  const onProcessExit = () => {
+    if (child.exitCode === null) child.kill('SIGTERM')
+  }
+  child.once('error', (error) => {
+    console.error(`dsh-tui: failed to start Client process: ${error.message}`)
+    requestExit(1)
+    void release()
+  })
+  child.once('exit', (code, signal) => {
+    requestExit(code ?? (signal === 'SIGINT' ? 130 : 1))
+    void release()
+  })
+  process.once('exit', onProcessExit)
+
+  try {
+    connection = ctx.acpServer.connect(
+      bridge.nodeAcpStream(clientToAgent, agentToClient),
+    )
+    await connection
+  } catch (error) {
+    await release()
+    throw error
+  }
+  ctx.effect(() => release)
+}

package/lib/spawn-tui.js

@@ -0,0 +1,179 @@
+/**
+ * Spawn the platform-native `dsh-tui` binary for plugin / demo-skin attach.
+ *
+ * Unix extra fds: 3 = Node→TUI (Rust reads), 4 = TUI→Node (Rust writes).
+ * Windows (and DSH_TUI_FORCE_TCP=1): authenticated loopback TCP.
+ */
+
+import { spawn } from 'node:child_process'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import fs from 'node:fs'
+import { createServer } from 'node:net'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/** Select the first existing native painter in development-to-release order. */
+export function selectNativeBinary({ envBin, devBin, packagedBin }) {
+  for (const candidate of [envBin, devBin, packagedBin]) {
+    if (typeof candidate === 'string' && candidate.length > 0 && fs.existsSync(candidate)) {
+      return candidate
+    }
+  }
+  return undefined
+}
+
+/**
+ * Packaged native binary for this platform, or throw if it was not staged.
+ * Honors `DSH_TUI_BIN` when that path exists (source / cargo re-exec).
+ * @returns {string}
+ */
+export function nativeBinary() {
+  const envBin = process.env.DSH_TUI_BIN
+  const key = `${process.platform}-${process.arch}`
+  const exe = process.platform === 'win32' ? 'dsh-tui.exe' : 'dsh-tui'
+  const bin = path.join(__dirname, '..', 'vendor', key, exe)
+  const devBin = path.join(__dirname, '..', '..', 'target', 'debug', exe)
+  const selected = selectNativeBinary({ envBin, devBin, packagedBin: bin })
+  if (selected === undefined) {
+    let have = []
+    try {
+      have = fs.readdirSync(path.join(__dirname, '..', 'vendor'))
+    } catch {
+      // vendor dir missing entirely
+    }
+    throw new Error(
+      `martty: no native binary for ${key}` +
+        ` (packaged: ${have.join(', ') || 'none'});` +
+      ' rebuild the package on this machine with scripts/build-npm.sh',
+    )
+  }
+  return selected
+}
+
+/**
+ * Spawn the TUI in attach mode. Extra args are appended after `--attach-fds`
+ * or `--attach-tcp <addr>`. `--demo-skin` is dropped so Node cannot re-exec
+ * itself in a loop.
+ * @param {string} bin
+ * @param {string[]} [extraArgs]
+ * @param {{ stdin?: number | 'inherit', stdout?: number | 'inherit' }} [tty]
+ * @returns {Promise<{ child: import('node:child_process').ChildProcess, input: import('node:stream').Writable, output: import('node:stream').Readable, resume?: () => void }>}
+ */
+export async function spawnPluginTui(bin, extraArgs = [], tty = {}) {
+  const extra = extraArgs.filter((arg) => arg !== '--demo-skin')
+  const ttyIn = tty.stdin ?? 'inherit'
+  const ttyOut = tty.stdout ?? 'inherit'
+  const useTcp = process.platform === 'win32' || process.env.DSH_TUI_FORCE_TCP === '1'
+  if (!useTcp) {
+    const child = spawn(bin, ['--attach-fds', ...extra], {
+      stdio: [ttyIn, ttyOut, 'inherit', 'pipe', 'pipe'],
+    })
+
+    // Extra-fd writes race the TUI exiting (window closed, or the binary died
+    // before a JSON-RPC response flushed). Node treats EPIPE on a Socket with
+    // no 'error' listener as an unhandled exception; the child's 'exit' handler
+    // is the lifetime signal, so the stream error only needs to be non-fatal.
+    // Same posture as @deepseek-ai/dsh-sdk-client toward the runtime stdin.
+    child.stdio[3].on('error', () => {})
+    child.stdio[4].on('error', () => {})
+    return { child, input: child.stdio[4], output: child.stdio[3] }
+  }
+
+  const token = randomBytes(32).toString('hex')
+  const server = createServer()
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const address = server.address()
+  if (address === null || typeof address === 'string') {
+    server.close()
+    throw new Error('dsh-tui runner failed to allocate a loopback TCP port')
+  }
+
+  const authenticated = waitForAuthenticatedSocket(server, token)
+  const child = spawn(bin, ['--attach-tcp', `127.0.0.1:${address.port}`, ...extra], {
+    stdio: [ttyIn, ttyOut, 'inherit'],
+    env: { ...process.env, DSH_TUI_ATTACH_TOKEN: token },
+  })
+  let onChildError
+  let onChildExit
+  const childFailed = new Promise((_, reject) => {
+    onChildError = reject
+    onChildExit = (code, signal) => {
+      reject(new Error(`dsh-tui exited before connecting (code=${code}, signal=${signal})`))
+    }
+    child.once('error', onChildError)
+    child.once('exit', onChildExit)
+  })
+  try {
+    const socket = await Promise.race([authenticated, childFailed])
+    child.off('error', onChildError)
+    child.off('exit', onChildExit)
+    return { child, input: socket, output: socket, resume: () => socket.resume() }
+  } catch (error) {
+    server.close()
+    try {
+      child.kill('SIGTERM')
+    } catch {
+      // child may already be gone
+    }
+    throw error
+  }
+}
+
+function waitForAuthenticatedSocket(server, token) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      cleanup()
+      server.close()
+      reject(new Error('dsh-tui timed out connecting to the loopback transport'))
+    }, 10_000)
+    timeout.unref?.()
+
+    const cleanup = () => {
+      clearTimeout(timeout)
+      server.off('error', fail)
+      server.off('connection', authenticate)
+    }
+    const fail = (error) => {
+      cleanup()
+      reject(error)
+    }
+    const authenticate = (socket) => {
+      let buffered = Buffer.alloc(0)
+      const onData = (chunk) => {
+        buffered = Buffer.concat([buffered, chunk])
+        if (buffered.length > 1024) {
+          socket.destroy()
+          return
+        }
+        const newline = buffered.indexOf(0x0a)
+        if (newline < 0) return
+        socket.off('data', onData)
+        const supplied = buffered.subarray(0, newline).toString('utf8').trim()
+        const expectedBytes = Buffer.from(token)
+        const suppliedBytes = Buffer.from(supplied)
+        const valid = suppliedBytes.length === expectedBytes.length
+          && timingSafeEqual(suppliedBytes, expectedBytes)
+        if (!valid) {
+          socket.destroy()
+          return
+        }
+        socket.pause()
+        const remainder = buffered.subarray(newline + 1)
+        if (remainder.length > 0) socket.unshift(remainder)
+        cleanup()
+        server.close()
+        resolve(socket)
+      }
+      socket.on('data', onData)
+      socket.on('error', () => {})
+    }
+
+    server.on('error', fail)
+    server.on('connection', authenticate)
+  })
+}

package/lib/stats-view.js

@@ -0,0 +1,90 @@
+/** Built-in Client Plugin: standard ACP usage and timing in the composer dock. */
+
+export const name = 'stats-view'
+export const inject = ['acpSessionStats', 'tuiSlots']
+
+export function apply(ctx) {
+  let current = ctx.acpSessionStats.current()
+  let panel
+  const stopSlot = ctx.tuiSlots.inject('conversation.composer.dock', () => {
+    panel = ctx.tuiSlots.register(
+      { name: 'conversation.composer.dock', id: 'stats' },
+      nodesOf(current),
+    )
+    return () => panel.dispose()
+  })
+  const stopStats = ctx.acpSessionStats.subscribe((snapshot) => {
+    current = snapshot
+    panel?.update(nodesOf(current))
+  })
+  return () => {
+    stopStats?.()
+    stopSlot?.()
+  }
+}
+
+function nodesOf(snapshot) {
+  const usage = snapshot?.usage ?? {}
+  const stats = snapshot?.stats ?? {}
+  const nodes = []
+  if ((usage.input ?? 0) > 0 || (usage.output ?? 0) > 0) {
+    nodes.push(node('tokens', `Input ${formatTokens(usage.input)} tok · Output ${formatTokens(usage.output)} tok`))
+  }
+  if ((stats.turns ?? 0) > 0 || (stats.steps ?? 0) > 0) {
+    nodes.push(node(
+      'counts',
+      `${stats.turns ?? 0} ${plural(stats.turns ?? 0, 'turn')} · ${stats.steps ?? 0} ${plural(stats.steps ?? 0, 'step')}`,
+    ))
+  }
+  if ((usage.input ?? 0) > 0) {
+    const cacheRead = usage.cacheRead ?? usage.cached ?? 0
+    const cacheWrite = usage.cacheWrite ?? 0
+    const eligible = usage.input + cacheRead + cacheWrite
+    const rate = eligible > 0 ? Math.round(cacheRead / eligible * 100) : 0
+    nodes.push(node('cache', `Cache hit ${rate}%`))
+  }
+  if ((stats.llmMillis ?? 0) > 0 || (stats.toolMillis ?? 0) > 0) {
+    nodes.push(node(
+      'time',
+      `LLM ${formatDuration(stats.llmMillis ?? 0)} · Tool call ${formatDuration(stats.toolMillis ?? 0)}`,
+    ))
+  }
+  if ((stats.ttftCount ?? 0) > 0 || ((usage.output ?? 0) > 0 && (stats.llmMillis ?? 0) > 0)) {
+    const parts = []
+    if ((stats.ttftCount ?? 0) > 0) {
+      parts.push(`TTFT avg ${formatDuration(stats.ttftTotalMillis / stats.ttftCount)}`)
+    }
+    if ((usage.output ?? 0) > 0 && (stats.llmMillis ?? 0) > 0) {
+      parts.push(`${formatRate(usage.output / (stats.llmMillis / 1000))} tok/s`)
+    }
+    nodes.push(node('speed', parts.join(' · ')))
+  }
+  return nodes
+}
+
+function node(id, title) {
+  return { id, kind: 'generic', title, body: '' }
+}
+
+function plural(value, singular) { return value === 1 ? singular : `${singular}s` }
+
+function formatTokens(value = 0) {
+  if (value < 1000) return String(value)
+  const unit = value < 1_000_000 ? 1000 : 1_000_000
+  const suffix = unit === 1000 ? 'K' : 'M'
+  const scaled = value / unit
+  const rounded = scaled >= 100 ? Math.round(scaled) : Math.round(scaled * 10) / 10
+  return `${rounded}${suffix}`
+}
+
+function formatDuration(ms) {
+  if (ms < 60_000) return `${Math.round(ms / 100) / 10}s`
+  const seconds = Math.round(ms / 1000)
+  return `${Math.floor(seconds / 60)}m${seconds % 60}s`
+}
+
+function formatRate(value) {
+  return String(Math.round(value * 10) / 10)
+}
+
+export { formatDuration, formatTokens, nodesOf }

package/lib/tui-commands.js

@@ -0,0 +1,144 @@
+/** Lifecycle-owned local slash commands for TUI Client Plugins. */
+
+import { Service } from '@deepseek-ai/cordis'
+import { CORDIS_METHODS } from './cordis-protocol.js'
+
+export const name = 'tui-commands'
+export const inject = []
+
+const PROTOCOL = 0
+const NAME = /^[a-z0-9][a-z0-9-]*$/
+
+class TuiCommandsService extends Service {
+  constructor(ctx, core) {
+    super(ctx, 'tuiCommands')
+    this.core = core
+  }
+
+  register(options, handler) {
+    return this.core.register(this.ctx, options, handler)
+  }
+
+  dispatch(params) {
+    return this.core.dispatch(params)
+  }
+
+  list() {
+    return this.core.list()
+  }
+
+  bindNotify(notify) {
+    return this.core.bindNotify(notify)
+  }
+}
+
+function validateCommand(options) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new Error('tuiCommands.register: options must be an object')
+  }
+  if (typeof options.name !== 'string' || !NAME.test(options.name)) {
+    throw new Error('tuiCommands.register: name must be a lowercase slash identifier without /')
+  }
+  if (typeof options.description !== 'string' || options.description.length === 0) {
+    throw new Error('tuiCommands.register: description must be a non-empty string')
+  }
+  const extra = Object.keys(options).filter((key) => key !== 'name' && key !== 'description')
+  if (extra.length > 0) {
+    throw new Error(`tuiCommands.register: unknown option field(s) ${extra.join(', ')}`)
+  }
+  return {
+    name: options.name,
+    description: options.description,
+  }
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ notify?: (method: string, params: object) => void }} [options]
+ */
+export function installTuiCommands(ctx, options = {}) {
+  const entries = new Map()
+  let send = typeof options.notify === 'function' ? options.notify : undefined
+
+  function publish() {
+    if (typeof send !== 'function') return
+    send(CORDIS_METHODS.commandsUpdate, {
+      protocol: PROTOCOL,
+      commands: [...entries.values()].map((entry) => ({ ...entry.command })),
+    })
+  }
+
+  function bindNotify(notify) {
+    if (typeof notify !== 'function') throw new Error('tuiCommands.bindNotify: notify must be a function')
+    send = notify
+    publish()
+  }
+
+  function register(effectCtx, options, handler) {
+    const command = validateCommand(options)
+    if (typeof handler !== 'function') {
+      throw new Error('tuiCommands.register: handler must be a function')
+    }
+    if (entries.has(command.name)) {
+      throw new Error(`tuiCommands.register: command "${command.name}" is already registered`)
+    }
+    const entry = { command, handler, active: false }
+    const setup = () => {
+      if (entries.has(command.name)) {
+        throw new Error(`tuiCommands.register: command "${command.name}" is already registered`)
+      }
+      entry.active = true
+      entries.set(command.name, entry)
+      publish()
+      return () => {
+        if (!entry.active) return
+        entry.active = false
+        if (entries.get(command.name) === entry) entries.delete(command.name)
+        publish()
+      }
+    }
+    const release = typeof effectCtx.effect === 'function'
+      ? effectCtx.effect(setup, `tuiCommands.register(${JSON.stringify(command.name)})`)
+      : setup()
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      return release?.()
+    }
+  }
+
+  async function dispatch(params) {
+    if (params === null || typeof params !== 'object' || params.protocol !== PROTOCOL) {
+      throw new Error('tuiCommands.dispatch: unsupported command payload')
+    }
+    const entry = entries.get(params.name)
+    if (entry === undefined || !entry.active) {
+      throw new Error(`tuiCommands.dispatch: command "${String(params.name)}" is not registered`)
+    }
+    const args = typeof params.args === 'string' ? params.args : ''
+    return entry.handler(args, { name: entry.command.name })
+  }
+
+  function list() {
+    return [...entries.values()].map((entry) => ({ ...entry.command }))
+  }
+
+  const core = { register, dispatch, list, bindNotify }
+  const service = typeof ctx.provide === 'function'
+    ? new TuiCommandsService(ctx, core)
+    : {
+        register(options, handler) {
+          return register(ctx, options, handler)
+        },
+        dispatch,
+        list,
+        bindNotify,
+      }
+  if (typeof ctx.provide !== 'function') ctx.tuiCommands = service
+  return service
+}
+
+export function apply(ctx) {
+  installTuiCommands(ctx)
+}