dsh-code 0.1.0 → 0.2.0

package/src/models.ts

@@ -0,0 +1,66 @@
+/**
+ * Model directory for the `/model` panel: the in-process equivalent of the
+ * web host's model catalog (`buildModelCatalog`), reading the advisory
+ * `ctx.llm` registry directly. Catalog membership is advisory — a route
+ * serving a model it stopped advertising stays usable — so selection never
+ * fails on catalog absence alone.
+ *
+ * @module @deepseek-ai/dsh-tui/models
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { LlmModelInfo } from '@deepseek-ai/dsh-llm'
+
+/** One selectable row in the `/model` panel. */
+export interface ModelRow {
+  /** Registered provider route. */
+  provider: string
+  /** Display name of the provider route. */
+  providerName: string
+  /** Provider-owned model id. */
+  model: string
+  /** Human-readable model name. */
+  modelName: string
+}
+
+/** The resolved directory: rows plus per-provider discovery failures. */
+export interface ModelDirectory {
+  /** Advisory rows, provider-major in registry order. */
+  rows: readonly ModelRow[]
+  /** Provider ids whose model listing failed; those providers contribute no rows. */
+  failures: readonly string[]
+}
+
+/**
+ * Load the selectable model directory from the live `ctx.llm` registry.
+ * Providers are listed synchronously; each provider's models are discovered
+ * with a bounded parallel fan-out whose failures degrade to that provider
+ * contributing no rows (mirrors the web catalog's per-provider failures).
+ * @param ctx - context carrying the `llm` service.
+ * @returns the resolved directory; empty rows when `llm` is unavailable.
+ */
+export async function loadModelDirectory(ctx: Context): Promise<ModelDirectory> {
+  const llm = ctx.get('llm')
+  if (llm === undefined) return { rows: [], failures: [] }
+  const providers = llm.listProviders()
+  const listed = await Promise.all(providers.map(async (provider) => {
+    try {
+      const models: readonly LlmModelInfo[] = await llm.listModels(provider.id)
+      return {
+        provider: provider.id,
+        providerName: provider.name,
+        models: models.map(model => ({
+          provider: provider.id,
+          providerName: provider.name,
+          model: model.id,
+          modelName: model.name,
+        })),
+      }
+    } catch {
+      return { provider: provider.id, providerName: provider.name, models: [] as ModelRow[], failed: true }
+    }
+  }))
+  const rows = listed.flatMap(entry => entry.models)
+  const failures = listed.filter(entry => 'failed' in entry && entry.failed === true).map(entry => entry.provider)
+  return { rows, failures }
+}

package/src/render/projection.ts

@@ -8,7 +8,10 @@
  */
 
 import { boundContextSummary, type ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, TodoItem } from '@deepseek-ai/dsh-session'
+// Type-only imports merge the plugin-owned SessionEventMap variants (command/*
+// from dsh-commands) into the union this reducer switches on.
+import type {} from '@deepseek-ai/dsh-commands'
 
 /** One user prompt line. */
 export interface UserEntry {
@@ -39,6 +42,21 @@ export interface ToolEntry {
   summary: string
 }
 
+/** One slash-command execution dispatched through `ctx.commands`. */
+export interface CommandEntry {
+  kind: 'command'
+  /** Pairing id shared with the matching `command/done`. */
+  commandId: string
+  /** Lowercase command name without the leading slash. */
+  name: string
+  /** Verbatim text following the command name. */
+  args: string
+  /** Execution state; `running` until the paired lifecycle event lands. */
+  state: 'running' | 'done' | 'error'
+  /** Handler outcome text, empty until it lands. */
+  summary: string
+}
+
 /** One turn-level failure surfaced from `turn/end`. */
 export interface ErrorEntry {
   kind: 'error'
@@ -47,7 +65,7 @@ export interface ErrorEntry {
 }
 
 /** Ordered transcript items the renderer draws. */
-export type TranscriptEntry = UserEntry | AssistantEntry | ToolEntry | ErrorEntry
+export type TranscriptEntry = UserEntry | AssistantEntry | ToolEntry | CommandEntry | ErrorEntry
 
 /** Cumulative token accounting folded from `assistant/message` usage reports. */
 export interface UsageTotals {
@@ -80,11 +98,18 @@ export interface TranscriptView {
   /** Text accumulated from `assistant/chunk` deltas since the last flush. */
   streaming: string
   /** Latest whole-list todo snapshot from `todo/write`, empty when none. */
-  todos: SessionEvent<'todo/write'>['data']['todos']
+  todos: readonly TodoItem[]
   /** True while a durable turn is open (`turn/start` … `turn/end`). */
   busy: boolean
   /** Figures the status line renders. */
   stats: TranscriptStats
+  /**
+   * The `provider/model` pair of the last `request/header` snapshot — the
+   * session's own model record, which a resumed TUI prefers over the
+   * deployment default (mirrors the web host's resume selection order).
+   * Empty before the session's first request.
+   */
+  model: string
   /**
    * Fold-internal timing anchors, never rendered: open step and tool-call
    * start timestamps the next `assistant/message` / `tool/result` resolves
@@ -105,6 +130,7 @@ export function createTranscriptView(): TranscriptView {
     streaming: '',
     todos: [],
     busy: false,
+    model: '',
     stats: { turns: 0, steps: 0, llmMs: 0, toolMs: 0, usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 } },
     anchors: { stepStart: new Map(), toolStart: new Map() },
   }
@@ -194,7 +220,15 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
     case 'todo/write':
       return { ...view, todos: event.data.todos }
     case 'turn/start':
-      return { ...view, busy: true, stats: { ...view.stats, turns: view.stats.turns + 1 } }
+      // The web todo projection clears on turn/start: a fresh turn's first
+      // write is the authoritative list, and a stale snapshot must not linger
+      // through a turn that has not written one yet.
+      return {
+        ...view,
+        busy: true,
+        todos: [],
+        stats: { ...view.stats, turns: view.stats.turns + 1 },
+      }
     case 'step/start':
       view.anchors.stepStart.set(`${event.data.turn}:${event.data.step}`, event.time)
       return { ...view, stats: { ...view.stats, steps: view.stats.steps + 1 } }
@@ -207,6 +241,38 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
         entries: [...view.entries, { kind: 'error', text: `${reason.error.code}: ${reason.error.message}` }],
       }
     }
+    case 'request/header': {
+      // The session's own model record: the latest snapshot's provider/model
+      // pair, exactly what a resumed TUI restores as the selection.
+      const config = event.data.header.config
+      return { ...view, model: `${config.provider}/${config.model}` }
+    }
+    case 'command/run': {
+      const data = event.data
+      return {
+        ...view,
+        entries: [...view.entries, {
+          kind: 'command',
+          commandId: data.commandId,
+          name: data.name,
+          args: data.args ?? '',
+          state: 'running',
+          summary: '',
+        }],
+      }
+    }
+    case 'command/done': {
+      const data = event.data
+      const entries = view.entries.map((entry) => {
+        if (entry.kind !== 'command' || entry.commandId !== data.commandId) return entry
+        return {
+          ...entry,
+          state: data.kind === 'success' ? 'done' as const : 'error' as const,
+          summary: boundContextSummary(data.text ?? ''),
+        }
+      })
+      return { ...view, entries }
+    }
     default:
       return view
   }

package/src/render/text.ts

@@ -0,0 +1,24 @@
+/**
+ * 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
+ * and tabs survive; everything else in C0/C1 plus DEL becomes a visible
+ * `\xNN` escape.
+ *
+ * @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
+
+/**
+ * Escape control characters so externally sourced text cannot drive the
+ * terminal.
+ * @param text - raw text from a session event, tool payload, or catalog.
+ * @returns text with every control character (except `\n`, `\t`) rendered
+ * as a literal `\xNN` escape.
+ */
+export function displayText(text: string): string {
+  return text.replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
+}

package/src/skills.ts

@@ -0,0 +1,104 @@
+/**
+ * User-invocable skill watch for the `/` completion menu: the in-process
+ * equivalent of the web ui-skill trigger source. Skills are NOT commands —
+ * picking one lands the literal `/name ` text in the input, and submitting
+ * it as a normal prompt lets the host's tool-skill pre-step inject the body
+ * (the only entry point for model-disabled skills). Command descriptors win
+ * on a name collision; see the runner's dispatch.
+ *
+ * @module @deepseek-ai/dsh-code/skills
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { isUserInvocable } from '@deepseek-ai/dsh-skill'
+import type { SkillSummary } from '@deepseek-ai/dsh-skill'
+
+/** One completion-menu row derived from a user-invocable skill. */
+export interface SkillRow {
+  /** Skill name; the literal `/name` text is what a pick lands. */
+  name: string
+  /** Human-readable description (suffixed when model-invocation is off). */
+  description: string
+  /** Whether the model may also invoke this skill by name. */
+  modelInvocable: boolean
+}
+
+/** The skill-catalog snapshot the completion menu subscribes to. */
+export interface SkillsView {
+  /** Name-sorted user-invocable rows; empty until the first load lands. */
+  readonly rows: readonly SkillRow[]
+  /** Subscribe to catalog changes; returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+  /** Retarget the agent whose workspace the catalog is read for. */
+  setAgent(agent: Agent): void
+}
+
+/** Internal shape shared by {@link watchSkills} and its test doubles. */
+interface SkillsWatch extends SkillsView {
+  setAgent(agent: Agent): void
+}
+
+function toRows(skills: readonly SkillSummary[]): readonly SkillRow[] {
+  return skills
+    .filter(skill => isUserInvocable(skill))
+    .map(skill => ({
+      name: skill.name,
+      description: skill.description,
+      modelInvocable: skill.invocation.modelInvocable === true,
+    }))
+    .sort((left, right) => left.name < right.name ? -1 : 1)
+}
+
+/**
+ * Watch the user-invocable skill catalog for one agent's workspace. The first
+ * load starts when the owning agent is known (`setAgent`); `skills/change`
+ * and agent retargets re-read. Read failures keep the last good rows (the
+ * next change notification is the retry surface) — a missing `skills`
+ * service leaves the view permanently empty.
+ * @param ctx - context carrying the `skills` service (optional).
+ * @returns the view the completion menu subscribes to.
+ */
+export function watchSkills(ctx: Context): SkillsWatch {
+  const skills = ctx.get('skills')
+  let agent: Agent | undefined
+  let rows: readonly SkillRow[] = []
+  const listeners = new Set<() => void>()
+
+  const reload = (): void => {
+    if (skills === undefined || agent === undefined) return
+    skills.list({
+      cwd: agent.session.header.cwd,
+      scope: agent,
+    }).then((summaries: readonly SkillSummary[]) => {
+      const next = toRows(summaries)
+      if (next.length === rows.length && next.every((row, index) => row.name === rows[index]?.name)) return
+      rows = next
+      for (const listener of listeners) listener()
+    }, () => {
+      // Discovery failure keeps the last good rows; the next skills/change
+      // notification is the retry surface (mirrors the web directory).
+    })
+  }
+
+  if (skills !== undefined) {
+    ctx.on('skills/change', reload)
+  }
+
+  const view: SkillsWatch = {
+    get rows(): readonly SkillRow[] {
+      return rows
+    },
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    setAgent(next: Agent): void {
+      agent = next
+      reload()
+    },
+  }
+  return view
+}

package/src/startup.ts

@@ -0,0 +1,91 @@
+/**
+ * The interactive terminal app's command-line provider: parses `--resume`,
+ * `--continue`, `--session`, 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).
+ * - 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'
+
+/** 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 kind: 'named'; readonly sessionId: string }
+  | { readonly kind: 'resume'; readonly sessionId: string }
+  | { readonly kind: 'latest' }
+
+/**
+ * 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')
+    .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
+`)
+}
+
+/**
+ * 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<{ resume?: string; continue?: boolean; session?: string }>()
+    const selected = [options.resume !== undefined, options.continue === true, options.session !== undefined]
+    if (selected.filter(Boolean).length > 1) {
+      program.error('error: --resume, --continue, and --session are mutually exclusive')
+    }
+    if (options.session !== undefined && options.session === '') {
+      program.error('error: --session needs an id')
+    }
+    if (options.resume !== undefined && options.resume === '') {
+      program.error('error: --resume needs a session id or id prefix')
+    }
+    const startup: TuiStartup = options.resume !== undefined
+      ? { kind: 'resume', sessionId: options.resume }
+      : options.continue === true
+        ? { kind: 'latest' }
+        : options.session !== undefined
+          ? { kind: 'named', sessionId: options.session }
+          : { kind: 'fresh' }
+    ctx.provide(TUI_STARTUP_SERVICE, { startup } satisfies { startup: TuiStartup })
+  })
+  parseCmdline(ctx, program)
+}

package/src/store.ts

@@ -8,7 +8,7 @@
  */
 
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { createTranscriptView, projectEvent, type TranscriptView } from './render/projection.ts'
+import { createTranscriptView, projectEvent, projectEvents, type TranscriptView } from './render/projection.ts'
 
 /** The externally readable, event-fed transcript store for one session. */
 export interface TranscriptStore {
@@ -21,11 +21,17 @@ export interface TranscriptStore {
 }
 
 /**
- * Create one transcript store.
+ * Create one transcript store, optionally seeded with replayed history. The
+ * seed folds synchronously BEFORE the first render, so a resumed session
+ * paints its full transcript on mount (no live `session/event` fires for
+ * constructor seeds — the store's `session/event` feed only carries new
+ * appends).
+ * @param replay - persisted events in `seq` order (e.g. a resumed session's
+ * constructor seed); folded once and never re-notified.
  * @returns the store the runner feeds and the renderer subscribes to.
  */
-export function createTranscriptStore(): TranscriptStore {
-  let view = createTranscriptView()
+export function createTranscriptStore(replay?: readonly SessionEvent[]): TranscriptStore {
+  let view = replay === undefined ? createTranscriptView() : projectEvents(replay)
   const listeners = new Set<() => void>()
   return {
     getView: () => view,