dsh-code 0.9.0 → 1.0.0

package/src/render/text.ts

@@ -1,150 +1,150 @@
-/**
- * Display-boundary sanitization for externally sourced text (model output,
- * tool payloads, skill descriptions). Control characters — including ANSI
- * CSI/OSC escape sequences — would otherwise pass through Ink into the
- * terminal, letting output rewrite the screen or inject prompts. Newlines
- * survive; everything else in C0/C1 plus DEL becomes a visible `\xNN`
- * escape, and bidi overrides / invisible format controls / Unicode line and
- * paragraph separators become a visible `\uXXXX` escape (terminal emulators
- * that render bidirectional text would otherwise reorder the displayed
- * glyphs and let a command read as something it is not).
- *
- * @module @deepseek-ai/dsh-code/render/text
- */
-
-/** C0 controls except tab (0x09) and newline (0x0a), plus DEL and C1. */
-const CONTROL_ESCAPE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu
-
-/**
- * Bidi overrides and isolates (U+202A-202E, U+2066-2069), the Arabic Letter
- * Mark (U+061C), directional and zero-width format characters (U+200B,
- * U+200E/200F, U+2060-2064, U+FEFF), and Unicode line/paragraph separators
- * (U+2028/2029). Terminal emulators with bidi support (Windows Terminal,
- * iTerm2, kitty, WezTerm) reorder or hide these, so they must never reach
- * the terminal raw.
- */
-const INVISIBLE_ESCAPE = /[\u061c\u200b\u200e\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u206f\ufeff]/gu
-
-/**
- * Escape control and deceptive characters so externally sourced text cannot
- * drive the terminal. C0/C1/DEL render as a literal `\xNN` escape; bidi,
- * invisible-format, and separator controls render as a literal `\uXXXX`
- * escape. Newlines and tabs survive (budgeted callers normalize tabs).
- * @param text - raw text from a session event, tool payload, or catalog.
- * @returns display-safe text with every injectable character made visible.
- */
-export function displayText(text: string): string {
-  return text
-    .replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
-    .replace(INVISIBLE_ESCAPE, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)
-}
-
-/** Collapse external text to one terminal-safe logical row. */
-export function singleLineText(text: string): string {
-  return displayText(text).replace(/\r?\n/gu, ' ↵ ').replace(/\t/gu, '  ')
-}
-
-/** Terminal-cell width matching the TUI's existing CJK-aware wrapping rule. */
-function cellWidth(text: string): number {
-  let columns = 0
-  for (const char of text) {
-    columns += (char.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1
-  }
-  return columns
-}
-
-/**
- * Truncate one display-safe row without ever exceeding its physical-column
- * budget. The ellipsis is included inside the budget, matching Codex's popup
- * truncation contract; the previous app-local helper appended it after the
- * row was already full and could force an extra terminal wrap.
- */
-export function truncateColumns(text: string, columns: number): string {
-  const limit = Math.max(0, Math.floor(columns))
-  if (limit === 0) return ''
-  if (cellWidth(text) <= limit) return text
-
-  const contentLimit = limit - 1
-  let used = 0
-  let result = ''
-  for (const char of text) {
-    const width = cellWidth(char)
-    if (used + width > contentLimit) break
-    result += char
-    used += width
-  }
-  return `${result}…`
-}
-
-/** A display-safe suffix bounded by terminal rows and columns. */
-export interface DisplayTail {
-  /** Sanitized suffix suitable for direct terminal rendering. */
-  text: string
-  /** Whether content before the returned suffix was omitted. */
-  truncated: boolean
-}
-
-/** Read one Unicode character immediately before `end`. */
-function previousCharacter(text: string, end: number): { char: string; start: number } {
-  const last = text.charCodeAt(end - 1)
-  if (last >= 0xdc00 && last <= 0xdfff && end >= 2) {
-    const first = text.charCodeAt(end - 2)
-    if (first >= 0xd800 && first <= 0xdbff) {
-      return { char: text.slice(end - 2, end), start: end - 2 }
-    }
-  }
-  return { char: text.slice(end - 1, end), start: end - 1 }
-}
-
-/**
- * Keep only the newest display-safe text that fits a terminal rectangle.
- * The scan walks backward and stops as soon as the suffix is full, so a long
- * reasoning stream does not rescan its entire accumulated prefix per chunk.
- * Explicit newlines and terminal wrapping both consume rows; tabs expand to
- * two spaces so terminal tab stops (which render at contextual column 8
- * boundaries, not at the budgeted cell count) cannot inflate the physical
- * row count of the live region.
- * @param text - raw externally sourced text.
- * @param columns - available terminal columns.
- * @param rows - available terminal rows.
- * @returns a sanitized bounded suffix and whether an earlier prefix was cut.
- */
-export function displayTail(text: string, columns: number, rows: number): DisplayTail {
-  const columnLimit = Math.max(1, Math.floor(columns))
-  const rowLimit = Math.max(1, Math.floor(rows))
-  const reversed: string[] = []
-  let row = 1
-  let used = 0
-  let end = text.length
-
-  while (end > 0) {
-    const previous = previousCharacter(text, end)
-    if (previous.char === '\n') {
-      if (row >= rowLimit) break
-      reversed.push('\n')
-      row += 1
-      used = 0
-      end = previous.start
-      continue
-    }
-
-    const safe = previous.char === '\t' ? '  ' : displayText(previous.char)
-    const width = cellWidth(safe)
-    if (used > 0 && used + width > columnLimit) {
-      if (row >= rowLimit) break
-      // Materialize the soft wrap. Ink otherwise reflows at word boundaries
-      // and can turn a cell-counted two-row suffix into three rendered rows.
-      reversed.push('\n')
-      row += 1
-      used = 0
-    }
-    const extraRows = Math.floor(Math.max(0, width - 1) / columnLimit)
-    if (row + extraRows > rowLimit) break
-    row += extraRows
-    reversed.push(safe)
-    used = extraRows === 0 ? used + width : width - extraRows * columnLimit
-    end = previous.start
-  }
-
-  return { text: reversed.reverse().join(''), truncated: end > 0 }
-}
+/**
+ * Display-boundary sanitization for externally sourced text (model output,
+ * tool payloads, skill descriptions). Control characters — including ANSI
+ * CSI/OSC escape sequences — would otherwise pass through Ink into the
+ * terminal, letting output rewrite the screen or inject prompts. Newlines
+ * survive; everything else in C0/C1 plus DEL becomes a visible `\xNN`
+ * escape, and bidi overrides / invisible format controls / Unicode line and
+ * paragraph separators become a visible `\uXXXX` escape (terminal emulators
+ * that render bidirectional text would otherwise reorder the displayed
+ * glyphs and let a command read as something it is not).
+ *
+ * @module @deepseek-ai/dsh-code/render/text
+ */
+
+/** C0 controls except tab (0x09) and newline (0x0a), plus DEL and C1. */
+const CONTROL_ESCAPE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu
+
+/**
+ * Bidi overrides and isolates (U+202A-202E, U+2066-2069), the Arabic Letter
+ * Mark (U+061C), directional and zero-width format characters (U+200B,
+ * U+200E/200F, U+2060-2064, U+FEFF), and Unicode line/paragraph separators
+ * (U+2028/2029). Terminal emulators with bidi support (Windows Terminal,
+ * iTerm2, kitty, WezTerm) reorder or hide these, so they must never reach
+ * the terminal raw.
+ */
+const INVISIBLE_ESCAPE = /[\u061c\u200b\u200e\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u206f\ufeff]/gu
+
+/**
+ * Escape control and deceptive characters so externally sourced text cannot
+ * drive the terminal. C0/C1/DEL render as a literal `\xNN` escape; bidi,
+ * invisible-format, and separator controls render as a literal `\uXXXX`
+ * escape. Newlines and tabs survive (budgeted callers normalize tabs).
+ * @param text - raw text from a session event, tool payload, or catalog.
+ * @returns display-safe text with every injectable character made visible.
+ */
+export function displayText(text: string): string {
+  return text
+    .replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
+    .replace(INVISIBLE_ESCAPE, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)
+}
+
+/** Collapse external text to one terminal-safe logical row. */
+export function singleLineText(text: string): string {
+  return displayText(text).replace(/\r?\n/gu, ' ↵ ').replace(/\t/gu, '  ')
+}
+
+/** Terminal-cell width matching the TUI's existing CJK-aware wrapping rule. */
+function cellWidth(text: string): number {
+  let columns = 0
+  for (const char of text) {
+    columns += (char.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1
+  }
+  return columns
+}
+
+/**
+ * Truncate one display-safe row without ever exceeding its physical-column
+ * budget. The ellipsis is included inside the budget, matching Codex's popup
+ * truncation contract; the previous app-local helper appended it after the
+ * row was already full and could force an extra terminal wrap.
+ */
+export function truncateColumns(text: string, columns: number): string {
+  const limit = Math.max(0, Math.floor(columns))
+  if (limit === 0) return ''
+  if (cellWidth(text) <= limit) return text
+
+  const contentLimit = limit - 1
+  let used = 0
+  let result = ''
+  for (const char of text) {
+    const width = cellWidth(char)
+    if (used + width > contentLimit) break
+    result += char
+    used += width
+  }
+  return `${result}…`
+}
+
+/** A display-safe suffix bounded by terminal rows and columns. */
+export interface DisplayTail {
+  /** Sanitized suffix suitable for direct terminal rendering. */
+  text: string
+  /** Whether content before the returned suffix was omitted. */
+  truncated: boolean
+}
+
+/** Read one Unicode character immediately before `end`. */
+function previousCharacter(text: string, end: number): { char: string; start: number } {
+  const last = text.charCodeAt(end - 1)
+  if (last >= 0xdc00 && last <= 0xdfff && end >= 2) {
+    const first = text.charCodeAt(end - 2)
+    if (first >= 0xd800 && first <= 0xdbff) {
+      return { char: text.slice(end - 2, end), start: end - 2 }
+    }
+  }
+  return { char: text.slice(end - 1, end), start: end - 1 }
+}
+
+/**
+ * Keep only the newest display-safe text that fits a terminal rectangle.
+ * The scan walks backward and stops as soon as the suffix is full, so a long
+ * reasoning stream does not rescan its entire accumulated prefix per chunk.
+ * Explicit newlines and terminal wrapping both consume rows; tabs expand to
+ * two spaces so terminal tab stops (which render at contextual column 8
+ * boundaries, not at the budgeted cell count) cannot inflate the physical
+ * row count of the live region.
+ * @param text - raw externally sourced text.
+ * @param columns - available terminal columns.
+ * @param rows - available terminal rows.
+ * @returns a sanitized bounded suffix and whether an earlier prefix was cut.
+ */
+export function displayTail(text: string, columns: number, rows: number): DisplayTail {
+  const columnLimit = Math.max(1, Math.floor(columns))
+  const rowLimit = Math.max(1, Math.floor(rows))
+  const reversed: string[] = []
+  let row = 1
+  let used = 0
+  let end = text.length
+
+  while (end > 0) {
+    const previous = previousCharacter(text, end)
+    if (previous.char === '\n') {
+      if (row >= rowLimit) break
+      reversed.push('\n')
+      row += 1
+      used = 0
+      end = previous.start
+      continue
+    }
+
+    const safe = previous.char === '\t' ? '  ' : displayText(previous.char)
+    const width = cellWidth(safe)
+    if (used > 0 && used + width > columnLimit) {
+      if (row >= rowLimit) break
+      // Materialize the soft wrap. Ink otherwise reflows at word boundaries
+      // and can turn a cell-counted two-row suffix into three rendered rows.
+      reversed.push('\n')
+      row += 1
+      used = 0
+    }
+    const extraRows = Math.floor(Math.max(0, width - 1) / columnLimit)
+    if (row + extraRows > rowLimit) break
+    row += extraRows
+    reversed.push(safe)
+    used = extraRows === 0 ? used + width : width - extraRows * columnLimit
+    end = previous.start
+  }
+
+  return { text: reversed.reverse().join(''), truncated: end > 0 }
+}

package/src/render/tool-detail.ts

@@ -11,6 +11,8 @@
  * @module @deepseek-ai/dsh-code/render/tool-detail
  */
 
+import { displayText, truncateColumns } from './text.ts'
+
 /** Budgets keeping one expanded card bounded on a terminal. */
 const MAX_DIFF_LINES = 200
 const MAX_READ_LINES = 120
@@ -67,7 +69,7 @@ export type ToolDetail =
 
 /** Truncate one line to the visible-column budget with an ellipsis marker. */
 function clipLine(text: string): string {
-  return text.length > MAX_LINE_COLUMNS ? `${text.slice(0, MAX_LINE_COLUMNS - 1)}…` : text
+  return truncateColumns(displayText(text), MAX_LINE_COLUMNS)
 }
 
 /** Split text into lines, dropping the trailing empty element of a final newline. */

package/src/session-directory.ts

@@ -59,9 +59,9 @@ export interface SessionRow {
 /** Case-insensitive filesystems (Windows, macOS) compare paths by lowercased form. */
 const CASE_INSENSITIVE_FS = process.platform === 'win32' || process.platform === 'darwin'
 
-/** True when the header describes a subagent conversation (durable lineage). */
+/** True only for delegated subagents; ordinary forks also carry lineage. */
 export function isSubagentSession(header: SessionHeader): boolean {
-  return header.origin === 'subagent' || header.parentSession !== undefined
+  return header.origin === 'subagent'
 }
 
 function comparablePath(value: string): string {
@@ -79,7 +79,7 @@ function comparablePath(value: string): string {
 }
 
 /** Platform-consistent path equality for session cwd comparisons. */
-export function samePath(left: string | undefined, right: string): boolean {
+function samePath(left: string | undefined, right: string): boolean {
   if (left === undefined) return false
   return comparablePath(left) === comparablePath(right)
 }

package/src/startup.ts

@@ -1,119 +1,136 @@
-/**
- * The interactive terminal app's command-line provider: parses `--resume`,
- * `--continue`, `--session`, `--mode`, `--theme`, and `--help`, then
- * publishes {@link TUI_STARTUP_SERVICE} for the runner to consume lazily.
- * Follows the headless bundle's startup shape (a commander action publishing
- * a service through {@link parseCmdline}).
- *
- * Semantics:
- * - `--resume <id|prefix>` — continue the persisted session whose id or unique
- *   id-prefix matches; the TUI replays its transcript and appends to the same
- *   durable log.
- * - `--continue` / `-c` — resume the most recently modified persisted session
- *   whose project directory matches the current working directory.
- * - `--session <id>` — create a new session under an explicit identity (the
- *   id must not exist yet).
- * - `--theme <dark|light|auto>` — the color palette; auto follows the
- *   terminal (dark fallback until OSC-11 detection lands).
- * - no flags — a fresh session with a minted id.
- *
- * @module @deepseek-ai/dsh-tui/startup
- */
-
-import { Command } from 'commander'
-import type { Context } from '@deepseek-ai/cordis'
-import { parseCmdline } from '@deepseek-ai/dsh-cmdline'
-import { THEME_NAMES, type ThemeName } from './theme.ts'
-
-/** Stable Cordis plugin name. */
-export const name = 'tui-startup'
-
-/** Services required before the invocation can be resolved. */
-export const inject = ['cmdlineArgs']
-
-/** Service provided by this plugin and injected by the terminal runner. */
-export const TUI_STARTUP_SERVICE = 'tuiStartup'
-
-/** How the runner obtains its session identity. */
-export type TuiStartup =
-  | { readonly kind: 'fresh'; readonly mode?: string; readonly theme?: ThemeName }
-  | { readonly kind: 'named'; readonly sessionId: string; readonly mode?: string; readonly theme?: ThemeName }
-  | { readonly kind: 'resume'; readonly sessionId: string; readonly theme?: ThemeName }
-  | { readonly kind: 'latest'; readonly theme?: ThemeName }
-
-export interface TuiStartupOptions {
-  readonly resume?: string
-  readonly continue?: boolean
-  readonly session?: string
-  readonly mode?: string
-  readonly theme?: ThemeName
-}
-
-/** Pure option policy shared by Commander and tests. */
-export function resolveTuiStartup(options: TuiStartupOptions): TuiStartup {
-  const selected = [options.resume !== undefined, options.continue === true, options.session !== undefined]
-  if (selected.filter(Boolean).length > 1) throw new Error('--resume, --continue, and --session are mutually exclusive')
-  if (options.session === '') throw new Error('--session needs an id')
-  if (options.resume === '') throw new Error('--resume needs a session id or id prefix')
-  if (options.mode === '') throw new Error('--mode needs a preset id')
-  if (options.mode !== undefined && (options.resume !== undefined || options.continue === true)) {
-    throw new Error('--mode applies only to a new session; it cannot be combined with --resume or --continue')
-  }
-  if (options.theme !== undefined && !THEME_NAMES.includes(options.theme)) {
-    throw new Error('--theme must be dark, light, or auto')
-  }
-  const theme = options.theme === undefined ? {} : { theme: options.theme }
-  return options.resume !== undefined
-    ? { kind: 'resume', sessionId: options.resume, ...theme }
-    : options.continue === true
-      ? { kind: 'latest', ...theme }
-      : options.session !== undefined
-        ? { kind: 'named', sessionId: options.session, ...options.mode === undefined ? {} : { mode: options.mode }, ...theme }
-        : { kind: 'fresh', ...options.mode === undefined ? {} : { mode: options.mode }, ...theme }
-}
-
-/**
- * This app's command: the launcher's flags this app owns, its description,
- * and its help text.
- * @returns a fresh program, so one process can parse more than once (tests).
- */
-function tuiCommand(): Command {
-  return new Command()
-    .name('dsh --profile cli')
-    .description('Claude-Code-style interactive terminal for DeepSeek Harness.')
-    .helpOption('-h, --help', 'show this help')
-    .option('-r, --resume <session>', 'resume the persisted session with this id (or unique id prefix)')
-    .option('-c, --continue', 'resume the most recent persisted session for this working directory')
-    .option('--session <id>', 'create a new session under this explicit id')
-    .option('--mode <preset>', 'agent preset for a newly created session')
-    .option('--theme <name>', 'color theme: dark (default), light, or auto')
-    .addHelpText('after', `
-Examples:
-  dsh --profile cli                       fresh session, minted id
-  dsh --profile cli --resume abc123       resume session by id prefix
-  dsh --profile cli --continue            resume the latest local session
-  dsh --profile cli --mode minimal        fresh session using the minimal preset
-  dsh --profile cli --theme light         light palette for bright terminals
-`)
-}
-
-/**
- * Parse the invocation and publish the startup service. Mutual exclusions are
- * usage errors rejected from the action before anything is provided.
- * @param ctx - plugin context carrying the command line and exit request.
- */
-export function apply(ctx: Context): void {
-  const program = tuiCommand()
-  program.action(() => {
-    const options = program.opts<TuiStartupOptions>()
-    let startup: TuiStartup | undefined
-    try {
-      startup = resolveTuiStartup(options)
-    } catch (error: unknown) {
-      program.error(`error: ${error instanceof Error ? error.message : String(error)}`)
-    }
-    if (startup === undefined) return
-    ctx.provide(TUI_STARTUP_SERVICE, { startup } satisfies { startup: TuiStartup })
-  })
-  parseCmdline(ctx, program)
-}
+/**
+ * The interactive terminal app's command-line provider: parses `--resume`,
+ * `--continue`, `--session`, `--mode`, `--theme`, `--image`, an optional
+ * initial prompt, and `--help`, then
+ * publishes {@link TUI_STARTUP_SERVICE} for the runner to consume lazily.
+ * Follows the headless bundle's startup shape (a commander action publishing
+ * a service through {@link parseCmdline}).
+ *
+ * Semantics:
+ * - `--resume <id|prefix>` — continue the persisted session whose id or unique
+ *   id-prefix matches; the TUI replays its transcript and appends to the same
+ *   durable log.
+ * - `--continue` / `-c` — resume the most recently modified persisted session
+ *   whose project directory matches the current working directory.
+ * - `--session <id>` — create a new session under an explicit identity (the
+ *   id must not exist yet).
+ * - `--theme <dark|light|auto>` — the color palette; auto follows the
+ *   terminal (dark fallback until OSC-11 detection lands).
+ * - no flags — a fresh session with a minted id.
+ *
+ * @module @deepseek-ai/dsh-tui/startup
+ */
+
+import { Command } from 'commander'
+import type { Context } from '@deepseek-ai/cordis'
+import { parseCmdline } from '@deepseek-ai/dsh-cmdline'
+import { THEME_NAMES, type ThemeName } from './theme.ts'
+
+/** Stable Cordis plugin name. */
+export const name = 'tui-startup'
+
+/** Services required before the invocation can be resolved. */
+export const inject = ['cmdlineArgs']
+
+/** Service provided by this plugin and injected by the terminal runner. */
+const TUI_STARTUP_SERVICE = 'tuiStartup'
+
+/** How the runner obtains its session identity. */
+export type TuiStartup =
+  | ({ readonly kind: 'fresh'; readonly mode?: string } & TuiStartupInput)
+  | ({ readonly kind: 'named'; readonly sessionId: string; readonly mode?: string } & TuiStartupInput)
+  | ({ readonly kind: 'resume'; readonly sessionId: string } & TuiStartupInput)
+  | ({ readonly kind: 'latest' } & TuiStartupInput)
+
+interface TuiStartupInput {
+  readonly theme?: ThemeName
+  readonly prompt?: string
+  readonly images?: readonly string[]
+}
+
+export interface TuiStartupOptions {
+  readonly resume?: string
+  readonly continue?: boolean
+  readonly session?: string
+  readonly mode?: string
+  readonly theme?: ThemeName
+  readonly prompt?: string
+  readonly images?: readonly string[]
+}
+
+/** Pure option policy shared by Commander and tests. */
+export function resolveTuiStartup(options: TuiStartupOptions): TuiStartup {
+  const selected = [options.resume !== undefined, options.continue === true, options.session !== undefined]
+  if (selected.filter(Boolean).length > 1) throw new Error('--resume, --continue, and --session are mutually exclusive')
+  if (options.session === '') throw new Error('--session needs an id')
+  if (options.resume === '') throw new Error('--resume needs a session id or id prefix')
+  if (options.mode === '') throw new Error('--mode needs a preset id')
+  if (options.mode !== undefined && (options.resume !== undefined || options.continue === true)) {
+    throw new Error('--mode applies only to a new session; it cannot be combined with --resume or --continue')
+  }
+  if (options.theme !== undefined && !THEME_NAMES.includes(options.theme)) {
+    throw new Error('--theme must be dark, light, or auto')
+  }
+  const input = {
+    ...(options.theme === undefined ? {} : { theme: options.theme }),
+    ...(options.prompt === undefined || options.prompt.trim() === '' ? {} : { prompt: options.prompt.trim() }),
+    ...(options.images === undefined || options.images.length === 0 ? {} : { images: [...options.images] }),
+  }
+  return options.resume !== undefined
+    ? { kind: 'resume', sessionId: options.resume, ...input }
+    : options.continue === true
+      ? { kind: 'latest', ...input }
+      : options.session !== undefined
+        ? { kind: 'named', sessionId: options.session, ...options.mode === undefined ? {} : { mode: options.mode }, ...input }
+        : { kind: 'fresh', ...options.mode === undefined ? {} : { mode: options.mode }, ...input }
+}
+
+/**
+ * This app's command: the launcher's flags this app owns, its description,
+ * and its help text.
+ * @returns a fresh program, so one process can parse more than once (tests).
+ */
+function tuiCommand(): Command {
+  return new Command()
+    .name('dsh --profile cli')
+    .description('DeepSeek Harness CLI core: the interactive coding terminal.')
+    .helpOption('-h, --help', 'show this help')
+    .option('-r, --resume <session>', 'resume the persisted session with this id (or unique id prefix)')
+    .option('-c, --continue', 'resume the most recent persisted session for this working directory')
+    .option('--session <id>', 'create a new session under this explicit id')
+    .option('--mode <preset>', 'agent preset for a newly created session')
+    .option('--theme <name>', 'color theme: dark (default), light, or auto')
+    .option('-i, --image <path>', 'attach an image to the initial prompt (repeatable)', (path, paths: string[]) => [...paths, path], [])
+    .argument('[prompt...]', 'initial prompt; sends immediately after startup')
+    .addHelpText('after', `
+Examples:
+  dsh --profile cli                       fresh session, minted id
+  dsh --profile cli --resume abc123       resume session by id prefix
+  dsh --profile cli --continue            resume the latest local session
+  dsh --profile cli --mode minimal        fresh session using the minimal preset
+  dsh --profile cli --theme light         light palette for bright terminals
+  dsh --profile cli "explain this repo"   start and send an initial prompt
+  dsh --profile cli -i diagram.png "review this diagram"
+`)
+}
+
+/**
+ * Parse the invocation and publish the startup service. Mutual exclusions are
+ * usage errors rejected from the action before anything is provided.
+ * @param ctx - plugin context carrying the command line and exit request.
+ */
+export function apply(ctx: Context): void {
+  const program = tuiCommand()
+  program.action((prompt: string[]) => {
+    const options = { ...program.opts<TuiStartupOptions>(), prompt: prompt.join(' ') }
+    let startup: TuiStartup | undefined
+    try {
+      startup = resolveTuiStartup(options)
+    } catch (error: unknown) {
+      program.error(`error: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (startup === undefined) return
+    ctx.provide(TUI_STARTUP_SERVICE, { startup } satisfies { startup: TuiStartup })
+  })
+  parseCmdline(ctx, program)
+}