martty 0.2.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenMA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/openma-ai/Martty/main/assets/tui-whale.svg" width="424" alt="DeepSeek Harness TUI whale" />
+</p>
+
+<h1 align="center">DeepSeek Harness TUI</h1>
+
+<p align="center">
+  Terminal-native ACP client UI with a Cordis client plugin tree.
+</p>
+
+---
+
+Native binaries are packaged for macOS arm64, macOS x64, Linux x64, and Windows
+x64. Requires Node.js 18+.
+
+## Recommended
+
+```sh
+npm install --global @deepseek-ai/dsh
+dsh plugin --profile tui add martty@latest
+dsh --profile tui
+```
+
+The profile command is the recommended install and upgrade path. It creates a
+missing profile and installs the TUI plus its ACP dependency; no global
+`dsh-tui` installation is required.
+
+The profile Host mounts the ACP plugin on Base, then starts a separate TUI
+Client process over standard ACP stdin/stdout. For standalone use, run
+`dsh-tui` and use `--agent <cmd>` plus repeated `--agent-arg <arg>` for another
+ACP server. The Node Client process owns a Cordis tree and starts the Rust painter. A sibling
+`tui-cordis-client-runner` publishes TUI Client capabilities and evaluates
+approved `code.client` packages from `dsh-tool-cordis` against that client tree.
+
+ACP is a runtime dependency of this package. On a profile that already carries
+a different version through the standard ACP bundle, the package manager may
+retain both copies, but the TUI bundle replaces that surface's rows and mounts
+only the plugin resolved from TUI's own dependency graph. The supported profile
+shape never runs two ACP surfaces for one TUI.
+
+The package carries ACP as a runtime dependency and exports its Creator Host
+overlay internally. The profile bundle mounts both on the Host Base tree;
+neither enters the Client tree. Creator adds TUI plugin guidance to the
+existing `cordis` preset and does not use ACP for skill registration.
+
+Node and Rust use inherited pipes on Unix and an authenticated loopback TCP
+socket on Windows. This compositor channel carries theme/render data only;
+agent traffic remains ACP.
+
+## Demo
+
+```sh
+dsh-tui --demo
+dsh-tui --demo-skin
+```
+
+`dsh-tui` is the primary command. `dsb` is a compatibility alias.
+
+## Highlights
+
+- Streamed reasoning, replies, tool activity, subagents, run state, and
+  token/cache metrics in one terminal timeline.
+- Agent-advertised models, compositions, permissions, authentication methods,
+  and invocable skills in one searchable slash menu.
+- Up to eight editable image chips per prompt, with clipboard/file staging and
+  metadata previews on kitty-capable terminals.
+- Terminal-aware Markdown for headings, lists, quotes, code, emphasis, links,
+  and mixed CJK/Latin text.
+- Durable sessions, queued follow-ups, immediate steering, readline editing,
+  platform-native modifier bindings, mouse selection, and inline-expanded tools.
+- Dark/light themes, clipboard routing for local, tmux, and SSH sessions, plus
+  the optional `/liang` pixel companion.
+- A root `chrome.right` plugin rail for validated TuiNode trees, with live
+  update/unload and Client inspect support for Creator-authored plugins.
+- Lifecycle-owned local commands and native slider overlays, plus transactions
+  over the current Session's standard ACP `configOptions`.
+- Dynamic `code.host` + `code.client` Packages with inspect/run lifecycle and
+  package-private Host/Client RPC over a negotiated `_dsh/cordis/*` ACP
+  extension. Ordinary ACP agents remain usable when they do not advertise it.
+
+## Plugin surface
+
+TUI extensions are ordinary Cordis plugins on the Node Client tree. A single
+plugin may register a theme, `chrome.right` nodes, slash commands, overlays,
+timers, Session config transactions, and Host/Client RPC; all contributions
+leave together when its fiber stops or `/theme` replaces the selected Theme
+Plugin. Plugins submit semantic data and never receive the TTY, Ratatui,
+absolute coordinates, compositor fds, or private transport methods.
+
+The versioned contract and examples live in the repository's
+[plugin API](https://github.com/openma-ai/Martty/blob/main/docs/plugins.en.md).
+
+The demo needs no API key or agent. Run `dsh-tui --help` for agent, model,
+credential, session, theme, and demo options.
+
+## Supported platforms
+
+| Node platform key | Binary |
+|---|---|
+| `darwin-arm64` | `vendor/darwin-arm64/dsh-tui` |
+| `darwin-x64` | `vendor/darwin-x64/dsh-tui` |
+| `linux-x64` | `vendor/linux-x64/dsh-tui` |
+| `linux-arm64` | `vendor/linux-arm64/dsh-tui` |
+| `win32-x64` | `vendor/win32-x64/dsh-tui.exe` |
+
+If installation succeeds but launch reports `no native binary for ...`, confirm
+that you installed the latest version and that your platform appears above.
+
+## Uninstall
+
+```sh
+npm uninstall --global martty
+```
+
+Source, screenshots, development commands, and architecture notes live in the
+[GitHub repository](https://github.com/openma-ai/Martty).
+
+[MIT](https://github.com/openma-ai/Martty/blob/main/LICENSE).

package/bin/dsh-tui.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { bootClient, parseClientArgv, painterArgs } from '../lib/boot.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const platformKey = process.platform + '-' + process.arch
+const vendorDir = path.join(__dirname, '..', 'vendor')
+const binaryName = process.platform === 'win32' ? 'dsh-tui.exe' : 'dsh-tui'
+const packaged = path.join(vendorDir, platformKey, binaryName)
+const envBin = process.env.DSH_TUI_BIN
+const binaryPath = typeof envBin === 'string' && envBin.length > 0 && fs.existsSync(envBin)
+  ? envBin
+  : packaged
+
+const argv = process.argv.slice(2)
+const wantDemoSkin = argv.includes('--demo-skin')
+const wantDemo = argv.includes('--demo')
+const wantHelp = argv.includes('-h') || argv.includes('--help')
+const wantVersion = argv.includes('-V') || argv.includes('--version')
+
+if (!fs.existsSync(binaryPath)) {
+  let available = []
+  try {
+    available = fs
+      .readdirSync(vendorDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+  } catch {
+    // vendor dir missing entirely
+  }
+  console.error('dsh-tui: no bundled binary for this platform (' + platformKey + ').')
+  if (available.length > 0) {
+    console.error('Bundled platforms: ' + available.join(', '))
+  } else {
+    console.error('No platform binaries are bundled in this install.')
+  }
+  console.error('Hint: run scripts/build-npm.sh on this machine to build and package a native binary.')
+  process.exit(1)
+}
+
+function exitFromSpawn(result) {
+  process.exit(
+    result.status ??
+      (result.signal === 'SIGINT' ? 130 : result.signal === 'SIGTERM' ? 143 : 1),
+  )
+}
+
+if (wantHelp || wantVersion || wantDemo) {
+  exitFromSpawn(spawnSync(binaryPath, argv, { stdio: 'inherit' }))
+}
+
+if (wantDemoSkin) {
+  process.env.DSH_TUI_BIN ??= binaryPath
+  const demoSkinPath = path.join(__dirname, '..', 'lib', 'demo-skin.js')
+  const args = argv.filter((arg) => arg !== '--demo-skin')
+  exitFromSpawn(spawnSync(process.execPath, [demoSkinPath, ...args], {
+    stdio: 'inherit',
+    env: process.env,
+  }))
+}
+
+process.env.DSH_TUI_BIN ??= binaryPath
+const parsed = parseClientArgv(argv)
+await bootClient({ agent: parsed.agent, extraArgs: painterArgs(parsed) })

package/cordis.patch.yml

@@ -0,0 +1,30 @@
+# Host-side entries for the TUI profile surface. The ACP plugin mounts on the
+# existing Base Cordis tree. The runner starts a separate TUI Client process;
+# standard stdin/stdout carries ACP between them. Client plugins never mount
+# beside the Harness.
+
+# If this profile already carries an ACP surface bundle, TUI replaces its
+# provider/stdio rows with the same ACP plugin resolved through TUI's declared
+# dependency. The profile transport is replaced because its stdio belongs to
+# the TUI launcher, not an external ACP client. Missing ids are harmless.
+- id: acp-plugin
+  disabled: true
+
+- id: acp-server
+  disabled: true
+
+- id: acp-bridge
+  disabled: true
+
+- id: tui-creator-overlay
+  disabled: true
+
+- insert:
+    - id: tui-acp-host
+      name: 'martty/acp-host'
+
+    - id: tui-host-creator
+      name: 'martty/creator-overlay'
+
+    - id: tui-runner
+      name: 'martty/runner'

package/creator/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Internal bundle used by standalone dsh-tui when it spawns dsh-acp. This is
+# part of martty, not a separately published package.
+
+- insert:
+    - id: tui-creator-overlay
+      name: deepseek-harness-tui-creator-overlay

package/creator/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "deepseek-harness-tui-creator-overlay",
+  "private": true,
+  "main": "../lib/creator-overlay.js",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/lib/acp-client-events.js

@@ -0,0 +1,65 @@
+/** Effect-scoped fan-out for standard ACP messages observed by Client plugins. */
+
+import { Service } from '@deepseek-ai/cordis'
+
+export const name = 'acp-client-events'
+export const inject = []
+
+class AcpClientEventsService extends Service {
+  constructor(ctx, core) {
+    super(ctx, 'acpClientEvents')
+    this.core = core
+  }
+
+  register(observer) { return this.core.register(this.ctx, observer) }
+  observeClient(message) { return this.core.observeClient(message) }
+  observeAgent(message) { return this.core.observeAgent(message) }
+}
+
+export function installAcpClientEvents(ctx) {
+  const observers = new Set()
+
+  function register(effectCtx, observer) {
+    if (observer === null || typeof observer !== 'object'
+      || (typeof observer.observeClient !== 'function'
+        && typeof observer.observeAgent !== 'function')) {
+      throw new Error('acpClientEvents.register: observeClient or observeAgent is required')
+    }
+    const setup = () => {
+      observers.add(observer)
+      return () => observers.delete(observer)
+    }
+    const release = typeof effectCtx?.effect === 'function'
+      ? effectCtx.effect(setup, 'acpClientEvents.register')
+      : setup()
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      return release?.()
+    }
+  }
+
+  function observeClient(message) {
+    for (const observer of [...observers]) observer.observeClient?.(message)
+  }
+
+  function observeAgent(message) {
+    for (const observer of [...observers]) observer.observeAgent?.(message)
+  }
+
+  const core = { register, observeClient, observeAgent }
+  const service = typeof ctx.provide === 'function'
+    ? new AcpClientEventsService(ctx, core)
+    : {
+        register(observer) { return register(ctx, observer) },
+        observeClient,
+        observeAgent,
+      }
+  if (typeof ctx.provide !== 'function') ctx.acpClientEvents = service
+  return service
+}
+
+export function apply(ctx) {
+  installAcpClientEvents(ctx)
+}

package/lib/acp-client.js

@@ -0,0 +1,114 @@
+/**
+ * Cordis plugin: attach to any ACP agent by spawn or an existing stream.
+ *
+ * Provides `ctx.acpClient` plus the standard-ACP-backed
+ * `ctx.acpSessionConfig`. Does not import a harness, dsh, or dsh-acp.
+ * Switching agents is `{ command, args }` (or `config.stream`).
+ */
+
+import { spawn } from 'node:child_process'
+import { installAcpClientEvents } from './acp-client-events.js'
+import { installAcpSessionConfig } from './acp-session-config.js'
+import { installAcpSessionPlan } from './acp-session-plan.js'
+import { installAcpSessionStats } from './acp-session-stats.js'
+
+export { installAcpSessionConfig } from './acp-session-config.js'
+export { installAcpSessionPlan } from './acp-session-plan.js'
+export { installAcpSessionStats } from './acp-session-stats.js'
+export { installAcpClientEvents } from './acp-client-events.js'
+
+export const name = 'acp-client'
+export const inject = []
+
+/** @type {null | { command: string, args: string[], child: import('node:child_process').ChildProcess, stdin: import('node:stream').Writable, stdout: import('node:stream').Readable, kind: 'spawn' }} */
+let liveAgent = null
+
+/**
+ * @typedef {{ command: string, args?: string[], env?: Record<string, string> }} AgentSpec
+ */
+
+/**
+ * @param {unknown} config
+ * @returns {AgentSpec}
+ */
+export function resolveAgent(config = {}) {
+  const fromConfig = config && typeof config === 'object' ? config.agent : undefined
+  if (fromConfig && typeof fromConfig === 'object' && typeof fromConfig.command === 'string') {
+    return {
+      command: fromConfig.command,
+      args: Array.isArray(fromConfig.args) ? fromConfig.args.map(String) : [],
+      ...(fromConfig.env !== undefined ? { env: fromConfig.env } : {}),
+    }
+  }
+  const envCmd = process.env.DSH_TUI_AGENT
+  if (typeof envCmd === 'string' && envCmd.trim().length > 0) {
+    const tokens = envCmd.trim().split(/\s+/)
+    return { command: tokens[0], args: tokens.slice(1) }
+  }
+  return { command: 'dsh-acp', args: [] }
+}
+
+/**
+ * @param {object} ctx
+ * @param {object} [config]
+ */
+export function apply(ctx, config = {}) {
+  const events = installAcpClientEvents(ctx)
+  const sessionConfig = installAcpSessionConfig(ctx)
+  const sessionPlan = installAcpSessionPlan(ctx)
+  const sessionStats = installAcpSessionStats(ctx)
+  events.register(sessionConfig)
+  events.register(sessionPlan)
+  events.register(sessionStats)
+  if (config.stream !== undefined && config.stream !== null) {
+    const service = {
+      kind: 'stream',
+      stdin: config.stream.stdin,
+      stdout: config.stream.stdout,
+      child: config.stream.child,
+    }
+    provide(ctx, service)
+    return
+  }
+  const agent = resolveAgent(config)
+  if (
+    liveAgent !== null
+    && liveAgent.child.exitCode === null
+    && liveAgent.command === agent.command
+    && JSON.stringify(liveAgent.args) === JSON.stringify(agent.args ?? [])
+  ) {
+    provide(ctx, liveAgent)
+    return
+  }
+  const child = spawn(agent.command, agent.args ?? [], {
+    stdio: ['pipe', 'pipe', 'inherit'],
+    env: { ...process.env, ...(agent.env ?? {}) },
+  })
+  child.stdin.on('error', () => {})
+  child.stdout.on('error', () => {})
+  const service = {
+    kind: 'spawn',
+    command: agent.command,
+    args: agent.args ?? [],
+    stdin: child.stdin,
+    stdout: child.stdout,
+    child,
+  }
+  liveAgent = service
+  provide(ctx, service)
+  process.once('exit', () => {
+    try {
+      child.kill('SIGTERM')
+    } catch {
+      // already gone
+    }
+  })
+}
+
+function provide(ctx, service) {
+  if (typeof ctx.provide === 'function') {
+    ctx.provide('acpClient', service)
+  } else {
+    ctx.acpClient = service
+  }
+}

package/lib/acp-host.js

@@ -0,0 +1,24 @@
+/** Resolve the embeddable ACP plugin from TUI's own dependency graph. */
+
+import { createRequire } from 'node:module'
+
+export const name = 'dsh-tui-acp-host'
+export const inject = ['loader']
+
+const requireFromTui = createRequire(import.meta.url)
+
+function ownAcpPlugin() {
+  const specifier = '@openma/deepseek-harness-acp/plugin'
+  try {
+    return requireFromTui.resolve(specifier)
+  } catch {
+    // A source-linked package may rely on the active profile's installation.
+    return specifier
+  }
+}
+
+export async function apply(ctx, config) {
+  const exports = await ctx.loader.import(ownAcpPlugin())
+  const plugin = ctx.loader.unwrapExports(exports)
+  await ctx.plugin(plugin, config)
+}