dsh-code 0.2.0 → 0.3.0

package/src/index.ts

@@ -20,7 +20,7 @@ import { installModelSelection } from '@deepseek-ai/dsh-agent'
 import type { Agent, ModelSelection, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-agent-default-model'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import { SessionId, type Session, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import { SessionId, type Session, type SessionEvent, type SessionHeader, type UserMessage } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 // Empty type imports carry the loader Context merge for the settlement await
 // and the cmdline Context merge for the appExit host value.
@@ -31,8 +31,11 @@ import { mountApprovalAnswerer, type ApprovalStore } from './approval.ts'
 import { isSlashLine, watchCommands, type CommandsView } from './commands.ts'
 import { internals, type TuiMount } from './internals.ts'
 import { loadModelDirectory, type ModelRow } from './models.ts'
+import { createMentions, type MentionsApi } from './mentions.ts'
+import { mountQuestionProvider, type QuestionStore } from './questions.ts'
 import { createTranscriptStore } from './store.ts'
 import { watchSkills, type SkillsView } from './skills.ts'
+import { toolArgumentsPreview } from './render/tool-preview.ts'
 import type { TuiStartup } from './startup.ts'
 
 /** Stable Cordis plugin name. */
@@ -136,19 +139,7 @@ function approvalCommandPreview(events: readonly { kind: string }[], callId: str
     candidate.kind === 'tool' && (candidate as { callId?: string }).callId === callId)
   if (entry === undefined) return ''
   const args = (entry as { arguments?: string }).arguments ?? ''
-  try {
-    const parsed: unknown = JSON.parse(args)
-    if (parsed !== null && typeof parsed === 'object') {
-      const record = parsed as Record<string, unknown>
-      for (const key of ['command', 'cmd', 'description', 'path', 'pattern', 'query']) {
-        const value = record[key]
-        if (typeof value === 'string' && value !== '') return value
-      }
-    }
-  } catch {
-    // Raw JSON parse failed: fall through to the bounded raw arguments.
-  }
-  return args.length > 80 ? `${args.slice(0, 77)}...` : args === '' ? toolName : args
+  return toolArgumentsPreview(args, toolName)
 }
 
 /** The runner's connection between the React app and the process side. */
@@ -261,6 +252,15 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     request => approvalCommandPreview(store.getView().entries, request.callId, request.toolName),
   )
 
+  // ask_user_question provider: the single UI provider on the shared service,
+  // one request on screen at a time. Plan reviews (exit_plan_mode) arrive
+  // through this same pipe.
+  const questions: QuestionStore = mountQuestionProvider(ctx)
+
+  // @mention support: workspace file scan plus the opt-in session-reference
+  // service (the patch mounts it); submission expands session mentions.
+  const mentions: MentionsApi = createMentions(ctx, agent, session.header.cwd ?? cwd)
+
   // The bridge the React app registers on mount: local notices from the
   // process side (unknown commands, switch confirmations, cancels).
   const bridge: AppBridge = { notify: () => {} }
@@ -283,36 +283,79 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       .then(() => { io.exit(0) })
   }
 
-  /** Dispatch one submitted line: slash commands to the registry, other text to the agent. */
-  const dispatch = (text: string): void => {
+  /** Run one slash line through the command registry (closed namespace). */
+  const runSlash = (line: string): void => {
+    const registry = ctx.get('commands')
+    if (registry === undefined) {
+      bridge.notify('no command registry is mounted in this composition')
+      return
+    }
+    const controller = new AbortController()
+    void registry.execute(agent, line, controller.signal).then((execution) => {
+      if (execution === undefined) {
+        // No command owns this line: send it verbatim so a user-invocable
+        // skill gesture (`/skill-name`) reaches the host's tool-skill
+        // pre-step injection — the web composer's same fall-through.
+        agent.followup(createUserMessage({
+          content: [{ type: 'text', text: line }],
+          source: { kind: 'user' },
+        }))
+      }
+    }, (error: unknown) => {
+      bridge.notify(`command failed: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+
+  /** Deliver one readable line to the agent, expanding session mentions first. */
+  const send = (text: string, mode: 'followup' | 'steer'): void => {
     const line = text.trim()
     if (line === '') return
-    if (isSlashLine(line)) {
-      const registry = ctx.get('commands')
-      if (registry === undefined) {
-        bridge.notify('no command registry is mounted in this composition')
-        return
-      }
-      const controller = new AbortController()
-      void registry.execute(agent, line, controller.signal).then((execution) => {
-        if (execution === undefined) {
-          // No command owns this line: send it verbatim so a user-invocable
-          // skill gesture (`/skill-name`) reaches the host's tool-skill
-          // pre-step injection — the web composer's same fall-through.
-          agent.followup(createUserMessage({
-            content: [{ type: 'text', text: line }],
-            source: { kind: 'user' },
-          }))
-        }
-      }, (error: unknown) => {
-        bridge.notify(`command failed: ${error instanceof Error ? error.message : String(error)}`)
+    // The command registry is a closed namespace: slash lines run out of
+    // band and never reach the model through this path (steering keeps the
+    // registry out of the inbox, so slash lines steer as literal text).
+    if (isSlashLine(line) && mode === 'followup') {
+      runSlash(line)
+      return
+    }
+    let parsed: ReturnType<typeof mentions.parse>
+    try {
+      parsed = mentions.parse(line)
+    } catch (error: unknown) {
+      bridge.notify(`invalid session reference: ${error instanceof Error ? error.message : String(error)}`)
+      return
+    }
+    const deliver = (readable: string, context?: UserMessage): void => {
+      // Session snapshots ride the inbox as model-facing context ahead of
+      // the readable message (upstream README wiring: inject before the
+      // followup/steer that wakes the driver).
+      if (context !== undefined) agent.inject(context)
+      const message = createUserMessage({
+        content: [{ type: 'text', text: readable }],
+        source: { kind: 'user' },
       })
+      if (mode === 'steer') {
+        agent.steer(message)
+        bridge.notify('steering queued — the next step sees it')
+      } else {
+        agent.followup(message)
+      }
+    }
+    if (parsed.references.length === 0) {
+      deliver(parsed.text)
       return
     }
-    agent.followup(createUserMessage({
-      content: [{ type: 'text', text: line }],
-      source: { kind: 'user' },
-    }))
+    const controller = new AbortController()
+    void mentions.prepare(parsed, controller.signal).then((prepared) => {
+      deliver(prepared.text, prepared.additionalContext)
+    }, (error: unknown) => {
+      if (controller.signal.aborted) return
+      bridge.notify(`session reference failed: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+
+  /** Dispatch one submitted line: slash commands to the registry, other text to the agent. */
+  const dispatch = (text: string): void => {
+    send(text, 'followup')
   }
 
   /**
@@ -321,13 +364,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
    * a turn, so this doubles as the busy-state submit path.
    */
   const steer = (text: string): void => {
-    const line = text.trim()
-    if (line === '') return
-    agent.steer(createUserMessage({
-      content: [{ type: 'text', text: line }],
-      source: { kind: 'user' },
-    }))
-    bridge.notify('steering queued — the next step sees it')
+    send(text, 'steer')
   }
 
   /** Interrupt the running turn (Esc); true when a turn was actually cancelled. */
@@ -338,6 +375,30 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     return true
   }
 
+  /**
+   * Cycle to the next permission preset (Shift+Tab, the Claude-Code
+   * permission-mode convention mapped onto dsh presets). A session in a
+   * custom knob state wraps to the first declared preset.
+   */
+  const cyclePermission = (): string => {
+    const service = ctx.get('permissionPresets') as
+      | {
+        names: readonly string[]
+        current(events: readonly SessionEvent[]): string
+        set(target: Session, preset: string): void
+      }
+      | undefined
+    if (service === undefined || service.names.length === 0) {
+      bridge.notify('permission presets are not mounted in this composition')
+      return ''
+    }
+    const at = service.names.indexOf(service.current(session.events))
+    const next = service.names[(at + 1) % service.names.length] ?? ''
+    if (next === '') return ''
+    service.set(session, next)
+    return next
+  }
+
   /** Apply one /model selection: takes effect from the next assembled step. */
   const selectModel = (row: ModelRow): string => {
     picked = { provider: row.provider, model: row.model }
@@ -351,6 +412,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   mountRef.current = io.mount(createElement(App, {
     store,
     approval,
+    questions,
     commands,
     skills,
     model: initialModel,
@@ -363,6 +425,8 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     interrupt,
     quit,
     loadModels: () => loadModelDirectory(ctx),
+    loadMentions: mentions.candidates,
+    cyclePermission,
     selectModel,
     onBridgeReady: (instance: AppBridge) => {
       bridge.notify = instance.notify

package/src/mentions.ts

@@ -0,0 +1,193 @@
+/**
+ * Workspace @mention support: file candidates from a bounded async scan of
+ * the session cwd, session candidates from the opt-in `sessionReferenceResolver`
+ * service, and submission preparation through its `prepare()` API. Picked
+ * session mentions land as canonical `@[label](dsh-session:…)` tokens; on
+ * submit the text is parsed back into readable `@label` text plus structured
+ * references, snapshots are injected via `agent.inject()` before the readable
+ * message wakes the driver (`followup` idle, `steer` running) — exactly the
+ * upstream README's wiring.
+ *
+ * @module @deepseek-ai/dsh-code/mentions
+ */
+
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import {
+  formatSessionReferenceMention,
+  parseSessionReferenceText,
+  type SessionReferenceCandidate,
+  type SessionReferenceInput,
+} from '@deepseek-ai/dsh-session-reference'
+
+/** Parsed submission text: readable text plus structured references. */
+type ParsedSessionReferenceText = ReturnType<typeof parseSessionReferenceText>
+
+/** One filesystem entry the @ menu can complete. */
+export interface FileCandidate {
+  /** Workspace-relative path with forward slashes. */
+  path: string
+  /** Entry kind; directories insert with a trailing slash. */
+  kind: 'file' | 'directory'
+}
+
+/** One merged menu candidate (files and sessions, already ranked). */
+export interface MentionCandidate {
+  /** Text inserted after the `@` (directories carry a trailing slash). */
+  label: string
+  /** Human-readable origin shown beside the label. */
+  description: string
+  /** Origin kind for icon/coloring decisions. */
+  kind: 'file' | 'directory' | 'session'
+}
+
+/** Prepared submission: readable content plus optional injected context. */
+export interface PreparedMention {
+  /** Readable text with mention tokens normalized to `@label`. */
+  text: string
+  /** Structured source sessions in appearance order (empty when none). */
+  references: SessionReferenceInput[]
+  /** Aggregated snapshot for `agent.inject()`, undefined without references. */
+  additionalContext?: import('@deepseek-ai/dsh-session').UserMessage
+}
+
+/** Directories never entered and files never listed during the scan. */
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'lib', 'dist', 'out', '.omc', 'coverage'])
+const MAX_FILES = 4000
+const MAX_DEPTH = 12
+
+/** Bounded async BFS scan of a workspace; unreadable entries are skipped. */
+export async function scanWorkspaceFiles(root: string, signal?: AbortSignal): Promise<readonly FileCandidate[]> {
+  const found: FileCandidate[] = []
+  const pending: Array<{ absolute: string; relative: string; depth: number }> = [{ absolute: root, relative: '', depth: 0 }]
+  const aborted = (): boolean => signal?.aborted === true
+  while (pending.length > 0 && found.length < MAX_FILES && !aborted()) {
+    const current = pending.shift()
+    if (current === undefined) break
+    let entries
+    try {
+      entries = await readdir(current.absolute, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (found.length >= MAX_FILES || aborted()) return found
+      if (entry.name.startsWith('.')) continue
+      const relative = current.relative === '' ? entry.name : `${current.relative}/${entry.name}`
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || current.depth + 1 > MAX_DEPTH) continue
+        pending.push({ absolute: join(current.absolute, entry.name), relative, depth: current.depth + 1 })
+      } else if (entry.isFile()) {
+        found.push({ path: relative, kind: 'file' })
+      }
+    }
+  }
+  return found.sort((left, right) => left.path < right.path ? -1 : 1)
+}
+
+/** True when every query character appears in order in the haystack. */
+function isSubsequence(query: string, haystack: string): boolean {
+  let at = 0
+  for (const char of haystack) {
+    if (char === query[at]) at += 1
+    if (at >= query.length) return true
+  }
+  return at >= query.length
+}
+
+/** Rank one file path against the typed query (community-TUI scoring shape). */
+function scoreFile(path: string, query: string): number {
+  const name = path.slice(path.lastIndexOf('/') + 1)
+  if (query === '') return 0
+  if (name === query) return 1000
+  if (name.startsWith(query)) return 900
+  if (name.includes(query)) return 700
+  if (path.includes(query)) return 500
+  if (isSubsequence(query, name)) return 300
+  return 0
+}
+
+/** The mention API the input editor and the runner share. */
+export interface MentionsApi {
+  /** Scanned workspace files, cached across one session. */
+  files(): Promise<readonly FileCandidate[]>
+  /** Ranked menu candidates for the typed `@` query. */
+  candidates(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]>
+  /** Parse submission text into readable text plus structured references. */
+  parse(text: string): ParsedSessionReferenceText
+  /**
+   * Snapshot references and build the injected context. Throws the service's
+   * typed error on failure — the caller restores the draft and notifies.
+   */
+  prepare(parsed: ParsedSessionReferenceText, signal?: AbortSignal): Promise<PreparedMention>
+  /** Canonical mention token for a picked session candidate. */
+  sessionMention(candidate: SessionReferenceCandidate): string
+}
+
+/**
+ * Create the mention API for one agent's workspace. A missing
+ * session-reference service degrades to file mentions only (the scan still
+ * works); `prepare` then passes text through untouched.
+ * @param ctx - context carrying the optional `sessionReferenceResolver`.
+ * @param agent - the session owner; excluded from its own candidates.
+ * @param cwd - workspace root to scan.
+ */
+export function createMentions(ctx: Context, agent: Agent, cwd: string): MentionsApi {
+  const resolver = ctx.get('sessionReferenceResolver')
+  let filesPromise: Promise<readonly FileCandidate[]> | undefined
+
+  return {
+    files(): Promise<readonly FileCandidate[]> {
+      filesPromise ??= scanWorkspaceFiles(cwd)
+      return filesPromise
+    },
+    async candidates(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]> {
+      const needle = query.trim()
+      const [files, sessions] = await Promise.all([
+        this.files(),
+        resolver === undefined
+          ? Promise.resolve([])
+          : resolver.listCandidates(agent, needle, 10, signal).catch(() => []),
+      ])
+      const fileRows: MentionCandidate[] = files
+        .filter(candidate => scoreFile(candidate.path, needle) > 0)
+        .sort((left, right) => scoreFile(right.path, needle) - scoreFile(left.path, needle))
+        .slice(0, 20)
+        .map(candidate => ({
+          label: candidate.path,
+          description: candidate.kind === 'directory' ? 'Folder' : 'File',
+          kind: candidate.kind,
+        }))
+      const sessionRows: MentionCandidate[] = sessions.map(candidate => ({
+        label: formatSessionReferenceMention(candidate),
+        description: `Session · ${candidate.cwd ?? '(no cwd)'}`,
+        kind: 'session',
+      }))
+      return [...sessionRows, ...fileRows]
+    },
+    parse(text: string): ParsedSessionReferenceText {
+      return parseSessionReferenceText(text)
+    },
+    async prepare(parsed: ParsedSessionReferenceText, signal?: AbortSignal): Promise<PreparedMention> {
+      if (parsed.references.length === 0 || resolver === undefined) {
+        return { text: parsed.text, references: parsed.references }
+      }
+      const prepared = await resolver.prepare(
+        agent,
+        [{ type: 'text', text: parsed.text }],
+        parsed.references,
+        signal,
+      )
+      return {
+        text: prepared.content.filter(block => block.type === 'text').map(block => block.text).join(''),
+        references: parsed.references,
+        additionalContext: prepared.additionalContext,
+      }
+    },
+    sessionMention(candidate: SessionReferenceCandidate): string {
+      return formatSessionReferenceMention({ sessionId: candidate.sessionId, label: candidate.label })
+    },
+  }
+}

package/src/questions.ts

@@ -0,0 +1,143 @@
+/**
+ * The terminal ask_user_question provider: registers the single UI provider
+ * on `ctx.userQuestions` and drives it with a FIFO queue — one question
+ * request on screen at a time, everything else waiting — then resolves the
+ * collected answers back into the tool's promise. The community TUI proved
+ * this exact pipeline shape; here the dialog is an Ink bar instead of a
+ * pi-tui inline modal.
+ *
+ * Plan reviews (`exit_plan_mode`) arrive through the same service with an
+ * `intent: { kind: 'plan-review' }` — the renderer highlights the approve
+ * option; the answer encoding is identical either way.
+ *
+ * @module @deepseek-ai/dsh-code/questions
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  UserQuestionError,
+  type AskUserQuestionAnswer,
+  type AskUserQuestionRequest,
+} from '@deepseek-ai/dsh-user-questions'
+
+/** One question request waiting on the human, with its settle channels. */
+export interface PendingQuestion {
+  /** The request the renderer walks through question by question. */
+  request: AskUserQuestionRequest
+  /** Resolve the provider promise with the collected answers. */
+  resolve(answers: AskUserQuestionAnswer): void
+  /** Reject the provider promise as aborted (also used for Esc cancel). */
+  reject(error: Error): void
+}
+
+/** The pending-question snapshot the renderer subscribes to. */
+export interface QuestionSnapshot {
+  /** The active request, or undefined when nothing is being asked. */
+  pending: PendingQuestion | undefined
+}
+
+/** Store the pending question lands in; the renderer reads, the provider writes. */
+export interface QuestionStore {
+  /** Subscribe to pending-state changes; returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+  /** Read the current snapshot (identity-stable between changes). */
+  getSnapshot(): QuestionSnapshot
+  /** Submit the collected answers for the active request and advance the queue. */
+  submit(pending: PendingQuestion, answers: AskUserQuestionAnswer): void
+  /** Cancel the active request (Esc) — rejects ASK_ABORTED and advances the queue. */
+  cancel(pending: PendingQuestion): void
+}
+
+const ABORT_ERROR = new UserQuestionError(
+  'ask_user_question was interrupted before the user answered',
+  'ASK_ABORTED',
+)
+
+/**
+ * Mount the single `ctx.userQuestions` UI provider over a FIFO queue.
+ * @param ctx - context carrying the `userQuestions` service (dsh-base).
+ * @returns the store the renderer subscribes to; a context without the
+ * service yields a permanently empty store.
+ */
+export function mountQuestionProvider(ctx: Context): QuestionStore {
+  const service = ctx.get('userQuestions')
+  let snapshot: QuestionSnapshot = { pending: undefined }
+  let active: PendingQuestion | undefined
+  const queue: PendingQuestion[] = []
+  const listeners = new Set<() => void>()
+  const set = (next: QuestionSnapshot): void => {
+    snapshot = next
+    for (const listener of listeners) listener()
+  }
+
+  /** Settle the active request and show the next queued one, if any. */
+  const advance = (): void => {
+    const next = queue.shift()
+    active = next
+    set({ pending: next })
+  }
+
+  if (service !== undefined) {
+    service.registerProvider({
+      ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
+        return new Promise((resolve, reject) => {
+          const pending: PendingQuestion = {
+            request,
+            resolve,
+            reject,
+          }
+          // Abort settles through the same channel as an Esc cancel: the
+          // owning tool/step died, so the answer must not linger.
+          const onAbort = (): void => {
+            if (active === pending) {
+              active = undefined
+              set({ pending: undefined })
+              advance()
+            } else {
+              const at = queue.indexOf(pending)
+              if (at >= 0) queue.splice(at, 1)
+            }
+            reject(ABORT_ERROR)
+          }
+          if (request.signal?.aborted === true) {
+            reject(ABORT_ERROR)
+            return
+          }
+          request.signal?.addEventListener('abort', onAbort, { once: true })
+          if (active === undefined) {
+            active = pending
+            set({ pending })
+          } else {
+            queue.push(pending)
+          }
+        })
+      },
+    })
+  }
+
+  return {
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    getSnapshot(): QuestionSnapshot {
+      return snapshot
+    },
+    submit(pending: PendingQuestion, answers: AskUserQuestionAnswer): void {
+      if (active !== pending) return
+      active = undefined
+      set({ pending: undefined })
+      pending.resolve(answers)
+      advance()
+    },
+    cancel(pending: PendingQuestion): void {
+      if (active !== pending) return
+      active = undefined
+      set({ pending: undefined })
+      pending.reject(ABORT_ERROR)
+      advance()
+    },
+  }
+}

package/src/render/animations.ts

@@ -0,0 +1,22 @@
+/**
+ * Terminal animation frame tables derived from the web design language:
+ * the StateDot "ongoing" pixel chase (3×3 ring, 125ms flat-hold brightness
+ * steps, 1s cycle) becomes the single-cell stepped pulse below, and the
+ * streaming caret blink is the Claude-Code convention. Pure functions only —
+ * the Ink layer owns timers and colors.
+ *
+ * @module @deepseek-ai/dsh-code/render/animations
+ */
+
+/** Single-cell stepped pulse: flat holds mirroring the web's 125ms keyframes. */
+export const PULSE_FRAMES = ['█', '█', '▆', '▃', '▁', '▃', '▆', '█'] as const
+
+/** Pulse frame for a monotonic tick. */
+export function pulseFrame(tick: number): string {
+  return PULSE_FRAMES[tick % PULSE_FRAMES.length] ?? PULSE_FRAMES[0]
+}
+
+/** Caret visibility: half the ticks on, half off (530ms blink). */
+export function caretVisible(tick: number): boolean {
+  return tick % 2 === 0
+}