dsh-oc-tui 0.1.0

package/README.md

@@ -0,0 +1,247 @@
+# Deepseek Harness opencode-like TUI Plugin
+
+An opencode-inspired **terminal UI (TUI)** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), shipped as a dsh profile app plugin. It boots a chat client inside the dsh process: it creates/resumes agents through `ctx.agents`, renders the durable `session/event` stream (user messages, streaming assistant tokens, tool cards, todo lists), routes human input back via `agent.followup()`, and answers `approval/request` prompts inline.
+
+The UI follows a DeepSeek blue-white dark design language (brand blue `#4D6BFE` accents on a blue-tinted canvas, with a blue→white gradient on the DeepSeek Harness title): a responsive session rail, markdown transcript and tool activity, a bordered multiline composer with slash-command suggestions, and a telemetry footer for session tokens, average time to first token (TTFT), decode throughput, KV-cache hit rate, and a **context meter** showing the current context length over the context-length limit. Thinking and running tools (read/write/...) show flowing spinner animations, the status row carries a flowing wave, and the composer border becomes a flowing gold marching-ants frame (dashes chasing clockwise around the box) while the agent is working.
+
+![max thinking effect](docs/max-thinking.gif)
+
+中文用户手册见 [docs/用户手册.md](docs/用户手册.md)。
+
+## Requirements
+
+- Node.js >= 22, an installed `@deepseek-ai/dsh` CLI, and an interactive terminal (Windows Terminal / ConPTY, iTerm2, GNOME Terminal, ...).
+- `pnpm` on PATH for the one-time plugin install (`dsh plugin` forwards to pnpm).
+- A configured model route: the profile reuses `$DSH_HOME/settings.yaml` (`llm-pi-ai` providers or `llm-deepseek`) and `$DSH_HOME/.credentials.yaml` — the same setup the Web GUI uses.
+
+## Quick start
+
+```sh
+# 1. One-time setup: create the tui profile and install this plugin into it.
+dsh plugin --profile tui add dsh-oc-tui
+
+# 2. Launch.
+dsh --profile tui
+```
+
+The first command initializes `$DSH_HOME/profiles/tui` with `@deepseek-ai/dsh-base`, installs this package with pnpm, and appends it to the profile's `dsh.profile.bundles` because the package declares `dsh.bundle`. Nothing else needs editing.
+
+Verify the layer without booting:
+
+```sh
+dsh --profile tui --dump-config
+```
+
+The dump shows the `dsh-oc-tui` bundle layer after `@deepseek-ai/dsh-base`.
+
+## Launch
+
+### `dsh --profile tui`
+
+The canonical launch is the dsh launcher itself:
+
+```sh
+dsh --profile tui                       # open the title screen; first message creates a session
+dsh --profile tui --resume <sessionId>  # resume a persisted session
+dsh --profile tui --model <modelId>     # default model for new sessions
+dsh --profile tui --provider <route>    # default provider route
+dsh --profile tui --no-sidebar          # start without the sidebar
+dsh --profile tui --help                # the TUI's own flags
+```
+
+The stock dsh launcher only hardcodes `web` and `plugin` as bare subcommands, so the profile flag is the intended shape for custom surfaces. If you want the exact string `dsh tui`, add a one-line shell alias (for example `doskey tui=dsh --profile tui $*` in CMD).
+
+### `dsh-oc-tui` convenience launcher
+
+The package also ships a `dsh-oc-tui` bin. It is equivalent to `dsh --profile tui`, but it verifies that the `tui` profile actually has the plugin installed and prints the one-time setup command when it does not:
+
+```sh
+dsh-oc-tui                 # boot the tui profile
+dsh-oc-tui --profile mytui # boot a profile with a different name
+dsh-oc-tui --help          # launcher help
+```
+
+The launcher prefers an installed `dsh` on PATH and falls back to `npx --yes @deepseek-ai/dsh`. Install the bin globally with `npm install -g dsh-oc-tui` (or run it from a local checkout with `node bin/dsh-oc-tui.js`). Environment overrides:
+
+| Variable | Effect |
+| --- | --- |
+| `DSH_TUI_PROFILE` | Default profile name when `--profile` is not given. |
+| `DSH_TUI_SKIP_CHECK` | Set to `1` to skip the profile preflight (advanced installs). |
+
+## Usage
+
+| Flag | Effect |
+| --- | --- |
+| `--resume <sessionId>` | Resume a persisted session by id. |
+| `--model <modelId>` | Default model id for new sessions. |
+| `--provider <provider>` | Default provider route for new sessions. |
+| `--sidebar` / `--no-sidebar` | Show (default) or hide the session sidebar. |
+| `--help` | Print the TUI's own flag help. |
+
+### Keybindings
+
+| Key | Action |
+| --- | --- |
+| Enter | send message |
+| Ctrl+Enter / Shift+Enter / Alt+Enter | insert a newline |
+| Ctrl+C | clear a non-empty prompt, cancel a running turn, or press twice while idle to exit |
+| Ctrl+P | open the settings menu |
+| Ctrl+E | toggle the thinking slider below the input box |
+| Tab | cycle the thinking intensity (session page); switch the settings left menu (settings page) |
+| Ctrl+N | new session |
+| Ctrl+D | delete the focused session in Settings → Manage sessions |
+| Ctrl+L | clear the transcript view |
+| Up / Down | move the caret across multi-line input; on the first/last row they step through input history |
+| Left / Right | move the caret left/right in the input box |
+| PgUp / PgDn | scroll the transcript |
+| Esc | close the context-meter panel / thinking slider / help, or cancel an approval prompt |
+| y / n | answer an inline approval prompt |
+
+Mouse: the wheel scrolls the transcript (or the settings window when Settings is open — it no longer moves the settings focus). Hold the left button and drag across the transcript to select text, then press the right button to copy the selection to the clipboard.
+
+### Commands
+
+`/help` `/settings` `/new` `/resume <id>` `/model <id>` `/provider <route>` `/clear` `/cancel` `/quit`
+
+Harness human commands (`/compact`, `/goal`, ...) are forwarded to `ctx.commands` and run without a model turn.
+
+## Install
+
+### Automatic install script
+
+The repo ships one-command installers for Linux/macOS and Windows. They check Node.js >= 22, ensure `pnpm` is present, install the plugin from GitHub into the `tui` profile, and can also install the `dsh-oc-tui` launcher globally.
+
+```sh
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/rayafriandion/dsh-oc-tui/main/install.sh | bash
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/rayafriandion/dsh-oc-tui/main/install.ps1 -OutFile install.ps1; & .\install.ps1"
+```
+
+From a checkout you can run `./install.sh` (Linux/macOS) or `.\install.ps1` (Windows) directly. Add `--launcher` / `-Launcher` to also put the `dsh-oc-tui` command on PATH:
+
+```sh
+./install.sh --launcher   # Linux/macOS
+.\install.ps1 -Launcher   # Windows
+```
+
+Other options: `--local` (`-Local`) installs the current checkout instead of GitHub, `--source <spec>` (`-Source <spec>`) uses a custom source (e.g. `dsh-oc-tui` once published to npm, or a tarball path), and `--profile <name>` (`-Profile <name>`) targets a non-default profile.
+
+### From the npm registry
+
+```sh
+dsh plugin --profile tui add dsh-oc-tui
+```
+
+### From a local checkout or tarball
+
+```sh
+dsh plugin --profile tui add ./dsh-oc-tui
+# or a packed tarball:
+dsh plugin --profile tui add ./dsh-oc-tui-0.1.0.tgz
+```
+
+`dsh plugin` anchors relative paths to your invoking directory before forwarding to pnpm.
+
+### From GitHub
+
+```sh
+dsh plugin --profile tui add github:you/dsh-oc-tui
+```
+
+This package ships plain JavaScript, so a git install needs no build step. pnpm ≥ 10 may still require allowlisting the git dependency's package key under `allowBuilds` in the profile's `pnpm-workspace.yaml` if a build step is ever added.
+
+### What the install does
+
+1. `dsh plugin` initializes `$DSH_HOME/profiles/tui` on first use (`@deepseek-ai/dsh-base` plus an empty user patch layer).
+2. pnpm installs `dsh-oc-tui` into the profile's `node_modules`.
+3. `dsh` appends `dsh-oc-tui` to `dsh.profile.bundles` because the package declares `dsh.bundle.patch`; the bundle patch inserts the `tui-startup` and `tui-app` rows.
+4. `dsh --profile tui` composes `@deepseek-ai/dsh-base` + `dsh-oc-tui` and boots the UI.
+
+To remove:
+
+```sh
+dsh plugin --profile tui remove dsh-oc-tui
+```
+
+## Settings
+
+The settings menu projects the same Host settings namespaces used by the WebUI and persists changes through `ctx.settings` to `$DSH_HOME/settings.yaml`. A left menu bar splits it into two tabs that `Tab` (or a click) switches: **Main** keeps the general settings — General (Busy Enter behavior, default agent and permission presets), Sessions (new session, session management), and System; **Model** merges the former provider settings and model settings into one tree: the default provider/model/reasoning choice, then one block per provider holding its Provider URL, Provider API key, and Models. Only providers you have actually added (present in your user settings layer) are listed — preset providers that were never added stay hidden. Under Models the saved selection is listed one row per model (Enter makes a listed model the default route); pressing Enter on the Models row auto-fetches the provider's advertised catalog (`ctx.llm.discoverModels` — the installed catalog for a known route, or an endpoint interrogation for a custom route) and opens a selection window of checkboxes where you choose which models to keep. The default agent preset is chosen from the roster the profile mounts (`agent-presets`): the shipped presets plus any you authored under `$DSH_HOME/.agent-presets`; TUI sessions keep composing process-wide from the base, so the stored default only applies where a session is created from a preset. WebUI-only options (`ui-theme` Appearance and `locale` Language) are intentionally not shown because they have no effect inside the TUI. Choice items open their option list with Enter - there is no inline left/right value cycling.
+
+**Thinking intensity.** The effective level stays visible on the composer's top-right border as the bare level name (no "effort" caption), diagonally opposite the `provider · model` label. Press `Tab` on the session page to cycle the intensity through the current model's levels (wrapping strongest → weakest); `Shift+Tab` steps backwards. Press `Ctrl+E` to open a slider below the input box; `Tab` or `←`/`→` move it and persist the choice, `Esc` or `Ctrl+E` closes it. The slider is driven by the current model's actual selectable levels reported by the provider adapter (`ctx.llm.resolveModelInfo`), so a boolean-thinking model shows exactly its two ends, a full-range model shows every level it advertises, and a partial model (for example DeepSeek's `Off`/`High`/`Max`) shows only those — never a blanket `none → max` scale. At the strongest available level, the track gradient and bright sweep move left to right, the empty track shimmers, and the top-right label receives a flowing gradient with a pulsing text arrow. The Settings → Model → Reasoning entry stays available as a list menu over the same levels. The chosen level is applied to the session's requests through the `agent/request` waterfall and stored in `agent-default-model.reasoningEffort`.
+
+**Context meter.** The status row carries a live context-occupancy bar (`ctx ▓▓░░ 32K/128K 25%`) fed by the token-meter `contextPressure` projection, the same source as the Web UI's composer ring. It shows the current context length over the context-length limit once the provider reports both; the fill shifts toward the warning/error palette as occupancy climbs. Click the meter (or press `Esc` to close) to open a breakdown panel with the occupancy reading and the heuristic composition shares — system prompt, tools, and messages — matching the Web UI's ContextMeter dialog. The meter stays hidden when the profile lacks the token-meter projections.
+
+## Plugin model
+
+This package is a DeepSeek Harness Cordis plugin, not a standalone agent runtime. The optional `dsh-oc-tui` binary only launches `dsh --profile tui`; DSH continues to own model routing, agent execution, tools, approvals, commands, durable sessions, and credentials. The plugin owns terminal input and presentation.
+
+## How it works
+
+- The plugin is a Cordis function plugin loaded by the `tui` profile. `lib/startup.js` parses the app's flags and provides the `tuiStartup` service; `lib/index.js` owns the UI loop.
+- `lib/term.js` is a zero-dependency terminal engine: raw mode, alternate screen, a diffing cell buffer, and a key decoder (truecolor ANSI, CJK-aware widths). It parks the (hidden) terminal cursor at the input caret so the OS IME anchors its composition window inside the composer, and it understands both SGR and legacy X10 mouse encodings so wheel/click bytes can never leak into the input text.
+- `lib/ui.js` is the responsive view model + renderer (DeepSeek blue-white theme, session rail, transcript, multiline composer, command suggestions, and telemetry footer). Rendered transcript lines are cached per block, only the visible window is materialised each frame, streaming paints are coalesced, and the live block is re-rendered on a short throttle — so render cost stays bounded and output speed does not degrade as the history grows. `thinking` content is shown inside a gray-emphasised box that stays collapsed while streaming, collapses by default once finished, and toggles on click; thinking and running tools animate with flowing spinners.
+- `lib/metrics.js` folds durable step/chunk/message events into session token, average TTFT, decode throughput, and disjoint-token cache-hit metrics.
+- `lib/interrupt.js` owns the clear/cancel/double-exit state machine used by stdin and `SIGINT`.
+- `lib/markdown.js` renders model output (headings, lists, quotes, code, inline spans) to styled lines.
+- Agents are created/resumed through `ctx.agents`, the transcript is rebuilt from `session.surface` on resume and fed live by `session/event` (including `assistant/chunk` streaming), model defaults come from `ctx.agentDefaultModel`, and approvals answer the `approval/request` waterfall inline.
+
+## Development
+
+```sh
+node tests/smoke.test.mjs     # standalone pure-module tests (no dsh needed)
+node --check lib/*.js         # syntax
+node --check bin/*.js         # launcher syntax
+```
+
+The full end-to-end path (profile boot → session → live LLM streaming → commands → clean exit) was verified through a pseudo-terminal (node-pty + ConPTY) on Windows.
+
+For a zero-install development bootstrap that avoids pnpm, create the profile once and point its `cordis.patch.yml` at this checkout with absolute module paths:
+
+```sh
+dsh --profile tui --dump-config   # initializes the base profile once
+```
+
+Then add to `$DSH_HOME/profiles/tui/cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: tui-startup
+      name: 'file:///D:/Projects/DeepSeekHarnessPlugins/dsh-oc-tui/lib/startup.js'
+    - id: tui-app
+      name: 'file:///D:/Projects/DeepSeekHarnessPlugins/dsh-oc-tui/lib/index.js'
+      config:
+        sidebar: true
+        showReasoning: true
+```
+
+The plugin's dsh imports resolve through the shared `$DSH_HOME/profiles/node_modules` fallback that dsh maintains, so no pnpm install into the plugin directory is required.
+
+## Known limitations
+
+- IME composition and bracketed-paste image attachments are not exposed by the zero-dependency terminal engine yet.
+- Saved sessions are managed from Settings → Manage sessions; the shared `sessionQuery` service is required for the list.
+- `dsh tui` as a bare subcommand needs a shell alias — the stock launcher hardcodes only `web` and `plugin` subcommands.
+- Editing the plugin source does not hot-reload (the profile's HMR root is the profile dir, not the plugin dir); restart the profile to pick up changes.
+- `--resume` and Settings → Manage sessions require the shared `sessionQuery` service (mounted by `dsh-base`).
+
+## Layout
+
+```
+lib/index.js        plugin entry: agents, events, input, commands, approvals
+lib/startup.js      command-line provider (tuiStartup service)
+lib/term.js         terminal engine (raw mode, screen, key decoding)
+lib/ui.js           responsive view model + renderer
+lib/metrics.js      durable event telemetry fold
+lib/interrupt.js    Ctrl+C lifecycle state
+lib/web-settings.js shared WebUI settings projection
+lib/markdown.js     markdown -> styled lines
+lib/util.js         text/display helpers
+bin/dsh-oc-tui.js  convenience launcher for `dsh --profile tui`
+install.sh          one-command installer (Linux/macOS)
+install.ps1         one-command installer (Windows)
+cordis.patch.yml    bundle patch layer (TUI rows)
+docs/用户手册.md      Chinese user manual
+tests/smoke.test.mjs  standalone smoke tests
+```

package/bin/dsh-oc-tui.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// dsh-oc-tui: convenience launcher for the DeepSeek Harness terminal UI.
+//
+// It is equivalent to `dsh --profile tui <args...>`, but it:
+//   1. prefers an installed dsh CLI on PATH,
+//   2. falls back to npx (@deepseek-ai/dsh) when dsh is not installed,
+//   3. verifies that the target profile exists and has this plugin installed,
+//      so a missing one-time setup prints the exact command instead of a
+//      confusing empty boot,
+//   4. accepts --profile <name> (or DSH_TUI_PROFILE) to target a non-default
+//      profile; every other argument is forwarded to the TUI app.
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { delimiter, dirname, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+
+const PACKAGE_NAME = 'dsh-oc-tui'
+const DSH_PACKAGE = '@deepseek-ai/dsh'
+
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+function printHelp() {
+  process.stdout.write(`dsh-oc-tui ${manifest.version} — launch the DeepSeek Harness terminal UI
+
+Usage:
+  dsh-oc-tui [--profile <name>] [app args...]
+
+The launcher boots the dsh profile that has ${PACKAGE_NAME} installed and
+forwards every other argument to the TUI app (--resume, --model, --provider,
+--sidebar, --no-sidebar; see dsh --profile <name> --help).
+
+Options:
+  --profile <name>   profile to boot (default: tui; env DSH_TUI_PROFILE)
+  -h, --help         show this help
+  -V, --version      show the dsh-oc-tui version
+
+One-time setup (requires pnpm on PATH):
+  dsh plugin --profile tui add ${PACKAGE_NAME}
+
+Then:
+  dsh-oc-tui
+`)
+}
+
+/**
+ * Parse the launcher's own arguments. The TUI app never sees --profile,
+ * --help, or --version; everything else is forwarded verbatim.
+ */
+function parseArgs(argv) {
+  let profile = process.env.DSH_TUI_PROFILE || 'tui'
+  const forwarded = []
+  let help = false
+  let version = false
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '-h' || arg === '--help') {
+      help = true
+    } else if (arg === '-V' || arg === '--version') {
+      version = true
+    } else if (arg === '--profile') {
+      const value = argv[++i]
+      if (value === undefined || value === '' || value.startsWith('-')) {
+        process.stderr.write('dsh-oc-tui: --profile needs a name\n')
+        process.exit(1)
+      }
+      profile = value
+    } else if (arg.startsWith('--profile=')) {
+      profile = arg.slice('--profile='.length)
+    } else {
+      forwarded.push(arg)
+    }
+  }
+  return { profile, forwarded, help, version }
+}
+
+/** The harness home directory, matching dsh's own DSH_HOME convention. */
+function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh')
+}
+
+/**
+ * Check whether `profile` has this plugin installed. The official install path
+ * lists the package in dsh.profile.bundles; the zero-install development path
+ * restates the rows with absolute paths in the profile's cordis.patch.yml, so
+ * either marker counts.
+ */
+function profileStatus(profile) {
+  const profileDir = join(dshHome(), 'profiles', profile)
+  const manifestPath = join(profileDir, 'package.json')
+  if (!existsSync(manifestPath)) return 'missing'
+  try {
+    const profileManifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    const bundles = profileManifest?.dsh?.profile?.bundles ?? []
+    if (bundles.includes(PACKAGE_NAME)) return 'ready'
+  } catch {
+    // A broken profile manifest is dsh's error to report, not the launcher's.
+    return 'ready'
+  }
+  const patchPath = join(profileDir, 'cordis.patch.yml')
+  if (existsSync(patchPath) && readFileSync(patchPath, 'utf8').includes(PACKAGE_NAME)) return 'ready'
+  return 'incomplete'
+}
+
+function checkProfile(profile, setupCommand) {
+  if (process.env.DSH_TUI_SKIP_CHECK === '1') return true
+  const status = profileStatus(profile)
+  if (status === 'ready') return true
+  if (status === 'missing') {
+    process.stderr.write(`dsh-oc-tui: profile '${profile}' is not set up.\n`)
+    process.stderr.write(`Create it once with (requires pnpm on PATH):\n  ${setupCommand}\n`)
+  } else {
+    process.stderr.write(`dsh-oc-tui: profile '${profile}' exists but does not have ${PACKAGE_NAME} installed.\n`)
+    process.stderr.write(`Add it once with:\n  ${setupCommand}\n`)
+  }
+  process.stderr.write(`Then run: dsh-oc-tui --profile ${profile}\n`)
+  process.stderr.write('Set DSH_TUI_SKIP_CHECK=1 to skip this check.\n')
+  return false
+}
+
+/** Find an executable by name on PATH, with Windows extension probing. */
+function findOnPath(name) {
+  const path = process.env.PATH || ''
+  const names = process.platform === 'win32' ? [name + '.cmd', name + '.exe', name] : [name]
+  for (const directory of path.split(delimiter)) {
+    if (directory === '') continue
+    for (const candidate of names) {
+      const full = join(directory, candidate)
+      if (existsSync(full)) return full
+    }
+  }
+  return undefined
+}
+
+/**
+ * Resolve the dsh package's bin entry from an npm shim next to its install
+ * (the shim directory is the npm prefix, so @deepseek-ai/dsh resolves from
+ * there). Returning the JS entry lets Windows run it through node directly,
+ * which avoids both the .cmd EINVAL hardening and shell-argument quoting.
+ */
+function resolveDshEntry(dshExecutable) {
+  try {
+    const packagePath = createRequire(resolve(dshExecutable)).resolve(`${DSH_PACKAGE}/package.json`)
+    const packageManifest = JSON.parse(readFileSync(packagePath, 'utf8'))
+    const entry = typeof packageManifest.bin === 'string'
+      ? packageManifest.bin
+      : packageManifest.bin?.dsh
+    if (typeof entry === 'string' && entry !== '') return resolve(dirname(packagePath), entry)
+  } catch {
+    // Not an npm shim beside the dsh install, or a non-npm layout.
+  }
+  return undefined
+}
+
+/** Spawn one resolved command, using node for npm shims on Windows when possible. */
+function spawnCommand(command, args) {
+  if (process.platform === 'win32') {
+    const entry = resolveDshEntry(command)
+    if (entry !== undefined) return spawn(process.execPath, [entry, ...args], { stdio: 'inherit' })
+    if (/\.(cmd|bat)$/i.test(command)) {
+      return spawn('cmd.exe', ['/d', '/s', '/c', command, ...args], { stdio: 'inherit' })
+    }
+  }
+  return spawn(command, args, { stdio: 'inherit' })
+}
+
+/** The npx fallback: prefer the npm CLI bundled with this Node, then PATH. */
+function npxCommand() {
+  const bundled = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npx-cli.js')
+  if (existsSync(bundled)) return { command: process.execPath, args: [bundled] }
+  const onPath = findOnPath('npx')
+  if (onPath !== undefined) return { command: onPath, args: [] }
+  return undefined
+}
+
+function launchDsh(profile, forwarded) {
+  const dshArgs = ['--profile', profile, ...forwarded]
+  const dshExecutable = findOnPath('dsh')
+  if (dshExecutable !== undefined) return spawnCommand(dshExecutable, dshArgs)
+  const npx = npxCommand()
+  if (npx !== undefined) return spawnCommand(npx.command, [...npx.args, '--yes', DSH_PACKAGE, ...dshArgs])
+  return undefined
+}
+
+function main() {
+  const { profile, forwarded, help, version } = parseArgs(process.argv.slice(2))
+  if (help) {
+    printHelp()
+    process.exit(0)
+  }
+  if (version) {
+    process.stdout.write(manifest.version + '\n')
+    process.exit(0)
+  }
+  if (profile === '' || profile === '.' || profile === '..' || profile === 'node_modules'
+    || profile.includes('/') || profile.includes('\\')) {
+    process.stderr.write(`dsh-oc-tui: invalid profile name ${JSON.stringify(profile)}\n`)
+    process.exit(1)
+  }
+  const setupCommand = findOnPath('dsh') !== undefined
+    ? `dsh plugin --profile ${profile} add ${PACKAGE_NAME}`
+    : `npx --yes ${DSH_PACKAGE} plugin --profile ${profile} add ${PACKAGE_NAME}`
+  if (!checkProfile(profile, setupCommand)) process.exit(2)
+
+  const child = launchDsh(profile, forwarded)
+  if (child === undefined) {
+    process.stderr.write(`dsh-oc-tui: could not find dsh or npx on PATH — install ${DSH_PACKAGE} first\n`)
+    process.exit(1)
+  }
+  child.on('error', (error) => {
+    process.stderr.write('dsh-oc-tui: failed to launch dsh: ' + error.message + '\n')
+    process.exit(1)
+  })
+  child.on('exit', (code, signal) => {
+    process.exit(code ?? (signal ? 1 : 0))
+  })
+}
+
+main()

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-oc-tui bundle patch: the terminal UI over the dsh-base layer.
+# Rows reference this package by name, so the package must be resolvable from
+# the profile — the official path is `dsh plugin --profile tui add
+# dsh-oc-tui`, which installs it into the profile's node_modules and
+# appends this bundle. The zero-install development bootstrap may instead
+# restate these rows in the profile's own patch with absolute module paths.
+
+- insert:
+    - id: tui-startup
+      name: 'dsh-oc-tui/startup'
+
+    - id: tui-app
+      name: 'dsh-oc-tui'
+      config:
+        sidebar: true
+        showReasoning: true
+
+    # The preset roster behind the Settings -> Default preset list.
+    # Sessions keep composing process-wide from the base (single-session TUI);
+    # this row only makes the roster and its settings namespace available.
+    - id: agent-presets
+      name: '@deepseek-ai/dsh-agent-presets'
+      config:
+        default: standard