dsh-code 0.9.1 → 1.0.1

package/src/attachments.ts

@@ -0,0 +1,128 @@
+/** Terminal image-file adapter over the Harness durable attachment service. */
+
+import { open, readFile, stat } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { basename, extname, isAbsolute, resolve } from 'node:path'
+import type { AttachmentStore, ImageMediaType, SaveImageAttachment } from '@deepseek-ai/dsh-attachment'
+import type { ImageBlock } from '@deepseek-ai/dsh-llm'
+
+/** A validated path retained in the editor until submission persists it. */
+export interface ImagePathInspection {
+  readonly path: string
+  readonly name: string
+  readonly mediaType: ImageMediaType
+  readonly bytes: number
+}
+
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif'])
+
+/** Detect the supported encoded raster formats from bytes, never from a path suffix. */
+export function detectImageMediaType(data: Uint8Array): ImageMediaType | undefined {
+  if (data.length >= 8 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47
+    && data[4] === 0x0d && data[5] === 0x0a && data[6] === 0x1a && data[7] === 0x0a) return 'image/png'
+  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg'
+  if (data.length >= 6) {
+    const signature = String.fromCharCode(...data.subarray(0, 6))
+    if (signature === 'GIF87a' || signature === 'GIF89a') return 'image/gif'
+  }
+  if (data.length >= 12
+    && String.fromCharCode(...data.subarray(0, 4)) === 'RIFF'
+    && String.fromCharCode(...data.subarray(8, 12)) === 'WEBP') return 'image/webp'
+  return undefined
+}
+
+/** Whether a path-like token is worth probing as an image attachment. */
+export function looksLikeImagePath(path: string): boolean {
+  return IMAGE_EXTENSIONS.has(extname(path).toLowerCase())
+}
+
+/** Parse a terminal paste/drop containing only one or more image paths. */
+export function parsePastedImagePaths(input: string): readonly string[] {
+  const text = input.trim()
+  if (text === '') return []
+  const tokens: string[] = []
+  const matcher = /"([^"]+)"|'([^']+)'|(\S+)/gu
+  for (const match of text.matchAll(matcher)) {
+    const token = match[1] ?? match[2] ?? match[3]
+    if (token === undefined) continue
+    let path = token
+    if (path.startsWith('file://')) {
+      try {
+        path = fileURLToPath(path)
+      } catch {
+        return []
+      }
+    }
+    if (!looksLikeImagePath(path)) return []
+    tokens.push(path)
+  }
+  return tokens
+}
+
+/** Validate path, byte size and encoded signature without writing an attachment object. */
+export async function inspectImagePaths(
+  paths: readonly string[],
+  attachments: AttachmentStore | undefined,
+  cwd = process.cwd(),
+): Promise<readonly ImagePathInspection[]> {
+  if (paths.length === 0) return []
+  if (attachments === undefined) throw new Error('image attachments are unavailable in this profile')
+  if (paths.length > attachments.imageLimits.maxImagesPerMessage) {
+    throw new Error(`too many images (${paths.length}; limit ${attachments.imageLimits.maxImagesPerMessage})`)
+  }
+  const inspected: ImagePathInspection[] = []
+  let totalBytes = 0
+  for (const raw of paths) {
+    const path = isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw)
+    let facts: Awaited<ReturnType<typeof stat>>
+    try {
+      facts = await stat(path)
+    } catch (error: unknown) {
+      throw new Error(`cannot read image "${raw}": ${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (!facts.isFile()) throw new Error(`image path is not a file: "${raw}"`)
+    if (facts.size > attachments.imageLimits.maxImageBytes) {
+      throw new Error(`image "${basename(path)}" is ${facts.size} bytes; limit ${attachments.imageLimits.maxImageBytes}`)
+    }
+    totalBytes += facts.size
+    if (totalBytes > attachments.imageLimits.maxMessageImageBytes) {
+      throw new Error(`image batch is ${totalBytes} bytes; limit ${attachments.imageLimits.maxMessageImageBytes}`)
+    }
+    const handle = await open(path, 'r')
+    try {
+      const signature = new Uint8Array(16)
+      const { bytesRead } = await handle.read(signature, 0, signature.length, 0)
+      const mediaType = detectImageMediaType(signature.subarray(0, bytesRead))
+      if (mediaType === undefined || !attachments.imageLimits.mediaTypes.includes(mediaType)) {
+        throw new Error(`unsupported image file "${raw}" (expected PNG, JPEG, WebP, or GIF)`)
+      }
+      inspected.push({ path, name: basename(path), mediaType, bytes: facts.size })
+    } finally {
+      await handle.close()
+    }
+  }
+  return inspected
+}
+
+/** Read, validate, and persist an ordered image path list as model content blocks. */
+export async function saveImagePaths(
+  paths: readonly string[],
+  attachments: AttachmentStore | undefined,
+): Promise<readonly ImageBlock[]> {
+  if (paths.length === 0) return []
+  if (attachments === undefined) throw new Error('image attachments are unavailable in this profile')
+  const inputs: SaveImageAttachment[] = []
+  for (const path of paths) {
+    let data: Uint8Array
+    try {
+      data = await readFile(path)
+    } catch (error: unknown) {
+      throw new Error(`cannot read image "${path}": ${error instanceof Error ? error.message : String(error)}`)
+    }
+    const mediaType = detectImageMediaType(data)
+    if (mediaType === undefined) throw new Error(`unsupported image file "${path}" (expected PNG, JPEG, WebP, or GIF)`)
+    inputs.push({ data, mediaType, name: basename(path) })
+  }
+  const refs = await attachments.saveImages(inputs)
+  return refs.map(attachment => ({ type: 'image', attachment }))
+}

package/src/authorization-panel.ts

@@ -0,0 +1,285 @@
+/** Bounded Ink surfaces for provider login and logout. */
+
+import { createElement, useEffect, useRef, useState, type ReactElement } from 'react'
+import { Box, Text, useInput, useStdout } from 'ink'
+import {
+  AuthorizationDeclinedError,
+  type AuthorizationInteraction,
+  type AuthorizationNotice,
+  type AuthorizationPrompt,
+  type AuthorizationStatus,
+} from '@deepseek-ai/dsh-authorization'
+import type { CredentialKey } from '@deepseek-ai/dsh-credentials'
+import type { ProviderAuthorizationRow } from './authorization.ts'
+import { panelViewport } from './render/inspector.ts'
+import { displayText, singleLineText, truncateColumns } from './render/text.ts'
+import { getPalette, inkColor } from './theme.ts'
+
+interface PromptReply {
+  readonly resolve: (value: string) => void
+  readonly reject: (reason: Error) => void
+  readonly detach: () => void
+}
+
+export interface ProviderAuthorizationPanelProps {
+  readonly row: ProviderAuthorizationRow
+  begin(
+    row: ProviderAuthorizationRow,
+    method: string,
+    interaction: AuthorizationInteraction,
+    signal: AbortSignal,
+  ): Promise<AuthorizationStatus>
+  cancel(key: CredentialKey): void
+  openUrl(url: string): boolean
+  copy(text: string): Promise<void>
+  done(): void
+  back(): void
+}
+
+/** Run one upstream authorization flow without letting notices or prompts exceed the panel budget. */
+export function ProviderAuthorizationPanel(props: ProviderAuthorizationPanelProps): ReactElement {
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  const [phase, setPhase] = useState<'methods' | 'running'>('methods')
+  const [cursor, setCursor] = useState(0)
+  const [notices, setNotices] = useState<readonly AuthorizationNotice[]>([])
+  const [prompt, setPrompt] = useState<AuthorizationPrompt | undefined>(undefined)
+  const [draft, setDraft] = useState('')
+  const [promptCursor, setPromptCursor] = useState(0)
+  const [error, setError] = useState<string | undefined>(undefined)
+  const [copyState, setCopyState] = useState<string | undefined>(undefined)
+  const controllerRef = useRef<AbortController | undefined>(undefined)
+  const replyRef = useRef<PromptReply | undefined>(undefined)
+  const openedUrls = useRef(new Set<string>())
+
+  const clearReply = (): void => {
+    replyRef.current?.detach()
+    replyRef.current = undefined
+    setPrompt(undefined)
+    setDraft('')
+    setPromptCursor(0)
+  }
+
+  const decline = (): void => {
+    const reply = replyRef.current
+    clearReply()
+    reply?.reject(new AuthorizationDeclinedError())
+  }
+
+  const stop = (): void => {
+    controllerRef.current?.abort()
+    controllerRef.current = undefined
+    props.cancel(props.row.key)
+    decline()
+  }
+
+  useEffect(() => () => {
+    controllerRef.current?.abort()
+    props.cancel(props.row.key)
+    const reply = replyRef.current
+    replyRef.current = undefined
+    reply?.detach()
+    reply?.reject(new AuthorizationDeclinedError())
+  }, [props.row.key])
+
+  const start = (method: string): void => {
+    setPhase('running')
+    setError(undefined)
+    setNotices([])
+    setCopyState(undefined)
+    const controller = new AbortController()
+    controllerRef.current = controller
+    const interaction: AuthorizationInteraction = {
+      notify(notice): void {
+        setNotices(current => [...current.slice(-19), notice])
+        if (notice.url !== undefined && !openedUrls.current.has(notice.url)) {
+          openedUrls.current.add(notice.url)
+          props.openUrl(notice.url)
+        }
+      },
+      prompt(next): Promise<string> {
+        return new Promise((resolve, reject) => {
+          const onWithdraw = (): void => {
+            if (replyRef.current?.reject !== reject) return
+            clearReply()
+            reject(new Error('authorization prompt was withdrawn'))
+          }
+          next.signal?.addEventListener('abort', onWithdraw, { once: true })
+          replyRef.current = {
+            resolve,
+            reject,
+            detach: () => next.signal?.removeEventListener('abort', onWithdraw),
+          }
+          setPrompt(next)
+          setDraft('')
+          setPromptCursor(0)
+        })
+      },
+    }
+    void props.begin(props.row, method, interaction, controller.signal).then((status) => {
+      controllerRef.current = undefined
+      clearReply()
+      if (status === 'authorized') props.done()
+      else props.back()
+    }, (reason: unknown) => {
+      controllerRef.current = undefined
+      clearReply()
+      if (controller.signal.aborted) {
+        props.back()
+        return
+      }
+      setError(reason instanceof Error ? reason.message : String(reason))
+      setPhase('methods')
+    })
+  }
+
+  const answer = (value: string): void => {
+    const reply = replyRef.current
+    clearReply()
+    reply?.resolve(value)
+  }
+
+  useInput((input, key) => {
+    if (phase === 'methods') {
+      if (key.escape || input === 'q') {
+        props.back()
+        return
+      }
+      if (props.row.methods.length === 0) return
+      if (key.upArrow) {
+        setCursor(current => (current + props.row.methods.length - 1) % props.row.methods.length)
+        return
+      }
+      if (key.downArrow) {
+        setCursor(current => (current + 1) % props.row.methods.length)
+        return
+      }
+      if (key.return) start(props.row.methods[cursor]?.id ?? props.row.methods[0]!.id)
+      return
+    }
+
+    if (key.escape) {
+      stop()
+      props.back()
+      return
+    }
+    const copyValue = notices.at(-1)?.code ?? notices.at(-1)?.url
+    if ((input === 'c' || input === 'C') && copyValue !== undefined) {
+      void props.copy(copyValue).then(
+        () => setCopyState('copied'),
+        reason => setCopyState(`copy failed: ${reason instanceof Error ? reason.message : String(reason)}`),
+      )
+      return
+    }
+    if (prompt === undefined) return
+    if (prompt.kind === 'select') {
+      if (prompt.options.length === 0) return
+      if (key.upArrow) {
+        setPromptCursor(current => (current + prompt.options.length - 1) % prompt.options.length)
+        return
+      }
+      if (key.downArrow) {
+        setPromptCursor(current => (current + 1) % prompt.options.length)
+        return
+      }
+      if (key.return) answer(prompt.options[promptCursor]?.id ?? prompt.options[0]!.id)
+      return
+    }
+    if (key.backspace || key.delete) {
+      setDraft(current => [...current].slice(0, -1).join(''))
+      return
+    }
+    if (key.return) {
+      if (draft.trim() !== '') answer(draft)
+      return
+    }
+    if (input !== '' && !key.ctrl && !key.meta) setDraft(current => current + input)
+  })
+
+  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
+  if (viewport.compact) {
+    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('provider login · esc cancel', viewport.contentColumns))
+  }
+
+  const rows: Array<{ key: string; text: string; color?: string; bold?: boolean }> = []
+  if (phase === 'methods') {
+    if (error !== undefined) rows.push({ key: 'error', text: `  ${singleLineText(error)}`, color: inkColor(getPalette().error) })
+    props.row.methods.forEach((method, index) => {
+      rows.push({
+        key: method.id,
+        text: `${index === cursor ? '› ' : '  '}${displayText(method.label)}`,
+        color: inkColor(index === cursor ? getPalette().brandBright : getPalette().dim),
+      })
+    })
+  } else {
+    notices.forEach((notice, index) => {
+      rows.push({ key: `notice-${index}`, text: `  ${displayText(notice.message)}` })
+      if (notice.url !== undefined) rows.push({ key: `url-${index}`, text: `  ${displayText(notice.url)}`, color: inkColor(getPalette().brandBright) })
+      if (notice.code !== undefined) rows.push({ key: `code-${index}`, text: `  code ${displayText(notice.code)}`, color: inkColor(getPalette().success), bold: true })
+    })
+    if (prompt !== undefined) {
+      rows.push({ key: 'prompt', text: `  ${displayText(prompt.message)}`, color: inkColor(getPalette().brandBright) })
+      if (prompt.kind === 'select') {
+        prompt.options.forEach((option, index) => rows.push({
+          key: `option-${option.id}`,
+          text: `${index === promptCursor ? '› ' : '  '}${displayText(option.label)}${option.description === undefined ? '' : ` · ${displayText(option.description)}`}`,
+          color: inkColor(index === promptCursor ? getPalette().brandBright : getPalette().dim),
+        }))
+      } else {
+        const shown = prompt.kind === 'secret' ? '•'.repeat([...draft].length) : displayText(draft)
+        rows.push({ key: 'draft', text: `  ${shown}▏`, color: inkColor(getPalette().text) })
+      }
+    } else {
+      rows.push({ key: 'waiting', text: '  waiting for provider…', color: inkColor(getPalette().dim) })
+    }
+    if (copyState !== undefined) rows.push({ key: 'copy', text: `  ${singleLineText(copyState)}`, color: inkColor(copyState === 'copied' ? getPalette().success : getPalette().error) })
+  }
+  const visible = rows.slice(Math.max(0, rows.length - viewport.bodyRows))
+  const footer = phase === 'methods'
+    ? '↑↓ choose · enter continue · esc/q back'
+    : 'enter answer · c copy URL/code · esc cancel login'
+  return createElement(
+    Box,
+    { flexDirection: 'column', width: viewport.outerColumns, paddingX: 1, borderStyle: 'round', borderColor: inkColor(getPalette().brand) },
+    createElement(Text, { color: inkColor(getPalette().brand), bold: true, wrap: 'truncate-end' }, truncateColumns(`/model · login ${displayText(props.row.label)}`, viewport.contentColumns)),
+    ...visible.map(row => createElement(Text, { key: row.key, color: row.color, bold: row.bold, wrap: 'truncate-end' }, truncateColumns(row.text, viewport.contentColumns))),
+    createElement(Text, { color: inkColor(getPalette().dim), wrap: 'truncate-end' }, truncateColumns(footer, viewport.contentColumns)),
+  )
+}
+
+export function ProviderAuthorizationLogoutPanel({ row, confirm, done, back }: {
+  row: ProviderAuthorizationRow
+  confirm(row: ProviderAuthorizationRow): Promise<void>
+  done(): void
+  back(): void
+}): ReactElement {
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | undefined>(undefined)
+  useInput((input, key) => {
+    if (busy) return
+    if (key.escape || input === 'n' || input === 'N') {
+      back()
+      return
+    }
+    if (input !== 'y' && input !== 'Y') return
+    setBusy(true)
+    setError(undefined)
+    void confirm(row).then(done, (reason: unknown) => {
+      setBusy(false)
+      setError(reason instanceof Error ? reason.message : String(reason))
+    })
+  })
+  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
+  if (viewport.compact) return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('y logout · n/esc back', viewport.contentColumns))
+  return createElement(
+    Box,
+    { flexDirection: 'column', width: viewport.outerColumns, paddingX: 1, borderStyle: 'round', borderColor: inkColor(getPalette().warn) },
+    createElement(Text, { color: inkColor(getPalette().warn), bold: true, wrap: 'truncate-end' }, truncateColumns('/model · logout provider', viewport.contentColumns)),
+    createElement(Text, { wrap: 'truncate-end' }, truncateColumns(`  remove ${displayText(row.label)} login record`, viewport.contentColumns)),
+    createElement(Text, { color: inkColor(getPalette().dim), wrap: 'truncate-end' }, truncateColumns('  provider endpoint and model configuration stay unchanged', viewport.contentColumns)),
+    error === undefined ? undefined : createElement(Text, { color: inkColor(getPalette().error), wrap: 'truncate-end' }, truncateColumns(`  ${singleLineText(error)}`, viewport.contentColumns)),
+    createElement(Text, { color: inkColor(getPalette().dim), wrap: 'truncate-end' }, truncateColumns(busy ? 'working…' : 'y confirm · n/esc back', viewport.contentColumns)),
+  )
+}

package/src/authorization.ts

@@ -0,0 +1,147 @@
+/** Terminal adapter over the Harness provider-authorization and credential-record seams. */
+
+import { spawn } from 'node:child_process'
+import type { Context } from '@deepseek-ai/cordis'
+import type {
+  AuthorizationEntry,
+  AuthorizationInteraction,
+  AuthorizationMethod,
+  AuthorizationStatus,
+} from '@deepseek-ai/dsh-authorization'
+import {
+  credentialKeyId,
+  credentialKeyScope,
+  type CredentialKey,
+  type CredentialRecordInfo,
+} from '@deepseek-ai/dsh-credentials'
+
+/** Record scope used by the upstream pi-ai adapter for provider logins. */
+const PI_AI_RECORD_SCOPE = 'llm-pi-ai'
+
+/** One provider login flow joined with its value-free stored-record facts. */
+export interface ProviderAuthorizationRow {
+  readonly key: CredentialKey
+  readonly provider: string
+  readonly label: string
+  readonly methods: readonly AuthorizationMethod[]
+  readonly inFlight: boolean
+  readonly record: CredentialRecordInfo
+}
+
+/** The provider-login directory plus non-fatal record lookup failures. */
+export interface ProviderAuthorizationDirectory {
+  readonly rows: readonly ProviderAuthorizationRow[]
+  readonly failures: readonly string[]
+}
+
+/** Load only model-provider flows; unrelated future authorization domains stay out of `/model`. */
+export async function loadProviderAuthorizations(ctx: Context): Promise<ProviderAuthorizationDirectory> {
+  const authorization = ctx.get('authorization')
+  const credentials = ctx.get('credentials')
+  if (authorization === undefined || credentials === undefined) return { rows: [], failures: [] }
+  const entries = authorization.list().filter(entry => credentialKeyScope(entry.key) === PI_AI_RECORD_SCOPE)
+  const failures: string[] = []
+  const rows = await Promise.all(entries.map(async (entry): Promise<ProviderAuthorizationRow> => {
+    let record: CredentialRecordInfo
+    try {
+      record = await credentials.describeRecord(entry.key)
+    } catch (error: unknown) {
+      failures.push(`${entry.label}: ${error instanceof Error ? error.message : String(error)}`)
+      record = { configured: false, writable: false }
+    }
+    return {
+      key: entry.key,
+      provider: credentialKeyId(entry.key),
+      label: entry.label,
+      methods: entry.methods,
+      inFlight: entry.inFlight,
+      record,
+    }
+  }))
+  return { rows, failures }
+}
+
+/** Subscribe to login settlement and credential-record changes. */
+export function subscribeProviderAuthorizations(ctx: Context, listener: () => void): () => void {
+  const settled = ctx.on('authorization/settled', (key) => {
+    if (credentialKeyScope(key) === PI_AI_RECORD_SCOPE) listener()
+  })
+  const records = ctx.on('credentials/record-updated', (key) => {
+    if (credentialKeyScope(key) === PI_AI_RECORD_SCOPE) listener()
+  })
+  return () => {
+    settled()
+    records()
+  }
+}
+
+/** Begin one provider login through the interaction surface owned by the caller. */
+export async function beginProviderAuthorization(
+  ctx: Context,
+  row: Pick<ProviderAuthorizationRow, 'key'>,
+  method: string,
+  interaction: AuthorizationInteraction,
+  signal?: AbortSignal,
+): Promise<AuthorizationStatus> {
+  const authorization = ctx.get('authorization')
+  if (authorization === undefined) throw new Error('provider login is unavailable in this profile')
+  return (await authorization.begin({ key: row.key, method, interaction, signal })).status
+}
+
+/** Cancel the attempt currently serving this provider, if any. */
+export function cancelProviderAuthorization(ctx: Context, key: CredentialKey): void {
+  ctx.get('authorization')?.cancel(key)
+}
+
+/** Remove an authorization record without changing the provider's settings profile. */
+export async function logoutProviderAuthorization(ctx: Context, row: ProviderAuthorizationRow): Promise<void> {
+  const credentials = ctx.get('credentials')
+  if (credentials === undefined) throw new Error('credential storage is unavailable in this profile')
+  const current = await credentials.describeRecord(row.key)
+  if (!current.configured) return
+  if (!current.writable) throw new Error('this login record is read-only')
+  await credentials.deleteRecord(row.key)
+}
+
+/** Open an authorization URL with the platform default browser, without invoking a shell. */
+export function openAuthorizationUrl(raw: string): boolean {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    return false
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') return false
+  const target = url.toString()
+  try {
+    const child = process.platform === 'win32'
+      ? spawn('explorer.exe', [target], { detached: true, stdio: 'ignore' })
+      : process.platform === 'darwin'
+        ? spawn('/usr/bin/open', [target], { detached: true, stdio: 'ignore' })
+        : spawn('xdg-open', [target], { detached: true, stdio: 'ignore' })
+    child.once('error', () => {})
+    child.unref()
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Compact value-free status for the provider list. */
+export function providerAuthorizationStatus(row: ProviderAuthorizationRow | undefined): string {
+  if (row === undefined) return 'login unavailable'
+  if (row.inFlight) return 'login in progress'
+  if (!row.record.configured) return 'not logged in'
+  return row.record.kind === 'grant' ? 'OAuth' : 'interactive API key'
+}
+
+/** Find a provider's login flow from a previously loaded directory. */
+export function authorizationForProvider(
+  directory: ProviderAuthorizationDirectory | undefined,
+  provider: string,
+): ProviderAuthorizationRow | undefined {
+  return directory?.rows.find(row => row.provider === provider)
+}
+
+/** Preserve the upstream entry type in declarations without leaking service internals into the TUI. */
+export type { AuthorizationEntry }

package/src/editor.ts

@@ -0,0 +1,51 @@
+/** Host editor and clipboard adapters used by the terminal surface. */
+
+import { spawn } from 'node:child_process'
+import type { TranscriptView } from './render/projection.ts'
+
+function waitForProcess(command: string, args: readonly string[], input?: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...args], {
+      stdio: input === undefined ? 'inherit' : ['pipe', 'ignore', 'pipe'],
+      windowsHide: true,
+    })
+    let stderr = ''
+    child.stderr?.on('data', chunk => { stderr += String(chunk) })
+    child.once('error', reject)
+    child.once('exit', code => {
+      if (code === 0) resolve()
+      else reject(new Error(`${command} exited with code ${String(code)}${stderr.trim() === '' ? '' : `: ${stderr.trim()}`}`))
+    })
+    if (input !== undefined) child.stdin?.end(input)
+  })
+}
+
+/** Copy UTF-8 text through the platform clipboard command. */
+export async function copyText(text: string): Promise<void> {
+  if (process.platform === 'win32') {
+    // Windows PowerShell 5 reads redirected stdin using the active console
+    // code page by default. Node writes UTF-8, so CJK copied through `$input`
+    // became mojibake. Set the pipe encoding before reading it.
+    await waitForProcess('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      '[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false); Set-Clipboard -Value ([Console]::In.ReadToEnd())',
+    ], text)
+    return
+  }
+  if (process.platform === 'darwin') {
+    await waitForProcess('pbcopy', [], text)
+    return
+  }
+  await waitForProcess('xclip', ['-selection', 'clipboard'], text)
+}
+
+/** Latest complete assistant text, excluding streaming and reasoning. */
+export function latestAssistantText(view: TranscriptView): string | undefined {
+  for (let index = view.entries.length - 1; index >= 0; index -= 1) {
+    const entry = view.entries[index]
+    if (entry?.kind === 'assistant' && entry.text !== '') return entry.text
+  }
+  return undefined
+}

package/src/fork.ts

@@ -0,0 +1,31 @@
+/** Pure session-fork boundary policy shared by the TUI command and tests. */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+export interface ForkSeed {
+  readonly boundarySeq: number
+  readonly events: readonly SessionEvent[]
+}
+
+/** Select a completed turn and trailing between-turn metadata. */
+export function selectForkSeed(events: readonly SessionEvent[], atSeq?: number): ForkSeed {
+  if (atSeq !== undefined && (!Number.isSafeInteger(atSeq) || atSeq < 0)) {
+    throw new Error('fork event sequence must be a non-negative integer')
+  }
+  const lastSeq = events.at(-1)?.seq ?? -1
+  const anchored = atSeq === undefined
+    ? undefined
+    : events.find(event => event.type === 'turn/end' && event.seq >= atSeq)
+  const boundary = anchored
+    ?? (atSeq === undefined || atSeq > lastSeq
+      ? events.findLast(event => event.type === 'turn/end')
+      : undefined)
+  if (boundary === undefined) {
+    throw new Error(atSeq !== undefined && atSeq <= lastSeq
+      ? `the turn containing event ${atSeq} has not completed`
+      : 'this session has no completed turn to fork from')
+  }
+  let cut = events.indexOf(boundary) + 1
+  while (cut < events.length && events[cut]?.type !== 'turn/start') cut += 1
+  return { boundarySeq: boundary.seq, events: events.slice(0, cut) }
+}