@qvac/core 0.1.0 → 0.1.2

package/tui/lib/render.mjs

@@ -0,0 +1,136 @@
+import { busyWord } from './busy-words.mjs'
+
+const PAYLOAD_FIELDS = {
+  content: 'content',
+  thinking: 'thinking',
+  'tool-call': 'toolCall',
+  'tool-result': 'toolResult',
+  attachment: 'attachment'
+}
+
+export function turnsFromChunks(chunks) {
+  const turns = []
+  const byRun = new Map()
+  for (const chunk of chunks) {
+    // deviceId (hex of the chunk's originDeviceId) lets a renderer label the
+    // human side per device — purely presentational, nothing schema-enforced.
+    if (chunk.type === 'user-message') {
+      turns.push({
+        from: 'user',
+        deviceId: chunk.originDeviceId?.toString('hex'),
+        segments: [{ type: 'user-message', text: chunk.userMessage.text }]
+      })
+      continue
+    }
+    // A user-uploaded attachment has no runId (it isn't part of an agent
+    // turn) — an attachment a tool call produced mid-run does, and groups
+    // into that run's turn below like any other segment.
+    if (chunk.type === 'attachment' && !chunk.runId) {
+      turns.push({
+        from: 'user',
+        deviceId: chunk.originDeviceId?.toString('hex'),
+        segments: [{ type: 'attachment', detail: chunk.attachment }]
+      })
+      continue
+    }
+    let turn = byRun.get(chunk.runId)
+    if (!turn) {
+      turn = { from: 'agent', runId: chunk.runId, status: null, segments: [] }
+      byRun.set(chunk.runId, turn)
+      turns.push(turn)
+    }
+    // The ask itself materializes the turn (so EVERY peer sees a run is in
+    // flight before the host even starts) but renders nothing of its own —
+    // the provider's run-status/content chunks are the visible side.
+    if (chunk.type === 'run-request') continue
+    if (chunk.type === 'run-status') {
+      turn.status = chunk.runStatus.state
+      turn.statusReason = chunk.runStatus.reason
+      turn.statusDetail = chunk.runStatus
+      // Status chunks are stamped by the device doing the work (the
+      // provider), so progress can be labelled with WHERE it's happening.
+      turn.statusDeviceId = chunk.originDeviceId?.toString('hex')
+      continue
+    }
+    // An approval-request chunk IS the approval state (see runAgent's
+    // createApprove) — never coalesced with a neighbor, and carries its own
+    // id so the UI can resolveApproval() it directly.
+    if (chunk.type === 'approval-request') {
+      turn.segments.push({ type: 'approval-request', id: chunk.id, detail: chunk.approvalRequest })
+      continue
+    }
+    // recovery appends a fresh sources chunk on the same run - the newest wins (v1 rule)
+    if (chunk.type === 'sources') {
+      const stale = turn.segments.findIndex((segment) => segment.type === 'sources')
+      if (stale >= 0) turn.segments.splice(stale, 1)
+      turn.segments.push({ type: 'sources', detail: chunk.sources })
+      continue
+    }
+    const detail = chunk[PAYLOAD_FIELDS[chunk.type]] ?? {}
+    const last = turn.segments[turn.segments.length - 1]
+    if (last && last.type === chunk.type) last.text += detail.text ?? ''
+    else {
+      turn.segments.push({
+        type: chunk.type,
+        text: detail.text ?? '',
+        detail
+      })
+    }
+  }
+  return turns
+}
+
+// The latest still-pending approval-request across every turn, or null —
+// there's at most one live tool call awaiting approval at a time (the
+// harness's own loop blocks on it before doing anything else).
+export function findPendingApproval(turns) {
+  for (let i = turns.length - 1; i >= 0; i--) {
+    for (const segment of turns[i].segments) {
+      if (segment.type === 'approval-request' && segment.detail.status === 'pending') return segment
+    }
+  }
+  return null
+}
+
+export function runningAgentTurn(turns) {
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const turn = turns[i]
+    if (turn.from === 'agent' && turn.status === 'executing') return turn
+  }
+  return null
+}
+
+const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled'])
+
+export function runInFlight(turns) {
+  for (let i = turns.length - 1; i >= 0; i--) {
+    if (turns[i].from !== 'agent') continue
+    return !TERMINAL_RUN_STATES.has(turns[i].status)
+  }
+  return false
+}
+
+export function busyStatus(modelState, runTurn) {
+  if (modelState?.status === 'loading') return { text: `loading ${modelState.model}…`, on: 'local' }
+  if (modelState?.status === 'downloading') {
+    return {
+      text: `downloading ${modelState.model}: ${Math.round(modelState.percentage ?? 0)}%`,
+      on: 'local'
+    }
+  }
+  if (modelState?.status === 'unloading') {
+    return { text: `unloading ${modelState.model}…`, on: 'local' }
+  }
+  const progress = runTurn?.statusDetail?.progress
+  if (progress?.phase === 'loading') return { text: `loading ${progress.model}…`, on: 'host' }
+  if (progress?.phase === 'downloading') {
+    return { text: `downloading ${progress.model}: ${progress.percentage ?? 0}%`, on: 'host' }
+  }
+  if (progress?.phase === 'generating') {
+    return { text: `generating image: ${progress.percentage ?? 0}%`, on: 'host' }
+  }
+  if (progress?.phase === 'queued') {
+    return { text: `queued - agent busy in ${progress.busyChatId}`, on: 'host' }
+  }
+  return { text: busyWord(runTurn?.runId), on: null }
+}

package/tui/lib/save-file.mjs

@@ -0,0 +1,71 @@
+import fs from 'fs'
+import path from 'path'
+
+export async function saveUniqueFile(dir, fileName, bytes, extension) {
+  const saved = await saveUnique(dir, fileName, extension, (handle) => write(handle, bytes))
+  return saved?.file ?? null
+}
+
+export function saveUniqueStream(dir, fileName, source, extension) {
+  return saveUnique(dir, fileName, extension, async (handle) => {
+    let bytesWritten = 0
+    for await (const data of source) bytesWritten += await write(handle, data)
+    return bytesWritten
+  })
+}
+
+async function saveUnique(dir, fileName, extension, writeFile) {
+  const tempDir = await fs.promises.mkdtemp(path.join(dir, '.qvac-download-'))
+  const tempFile = path.join(tempDir, 'download')
+  let handle = await fs.promises.open(tempFile, 'w')
+  let file = null
+
+  try {
+    file = await claimUniqueFile(dir, fileName, extension, tempFile)
+    if (!file) return null
+    const bytesWritten = await writeFile(handle)
+    await handle.close()
+    handle = null
+    return { file, bytesWritten }
+  } catch (err) {
+    await handle.close().catch(noop)
+    handle = null
+    if (file) await fs.promises.unlink(file).catch(noop)
+    throw err
+  } finally {
+    // Cleanup must not replace the download error or remove the reserved destination.
+    if (handle) await handle.close().catch(noop)
+    await fs.promises.rm(tempDir, { recursive: true, force: true }).catch(noop)
+  }
+}
+
+async function claimUniqueFile(dir, fileName, extension, source) {
+  const sanitized = path.basename(fileName).replace(/[^a-zA-Z0-9_.-]/g, '_')
+  const safe = !sanitized || sanitized === '.' || sanitized === '..' ? 'download' : sanitized
+  const dot = safe.lastIndexOf('.')
+  const base = (dot > 0 ? safe.slice(0, dot) : safe) || 'download'
+  const ext = extension === undefined ? (dot > 0 ? safe.slice(dot) : '') : extension
+
+  for (let n = 0; n < 100; n++) {
+    const file = path.join(dir, `${base}${n ? `-${n + 1}` : ''}${ext}`)
+    try {
+      // bare-fs does not preserve O_EXCL for concurrent opens; link is the atomic reservation.
+      await fs.promises.link(source, file)
+      return file
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+    }
+  }
+  return null
+}
+
+async function write(handle, data) {
+  let offset = 0
+  while (offset < data.length) {
+    const result = await handle.write(offset ? data.subarray(offset) : data)
+    offset += result.bytesWritten
+  }
+  return data.length
+}
+
+function noop() {}

package/tui/lib/select.mjs

@@ -0,0 +1,63 @@
+import { cells } from './wrap.mjs'
+
+const REVERSE = '\x1b[7m'
+const REVERSE_OFF = '\x1b[27m'
+// anything that would drop reverse video mid-span, the input's own cursor cell included
+const RESETS = new Set(['\x1b[0m', '\x1b[m', REVERSE_OFF])
+
+function ordered(anchor, focus) {
+  const [from, to] =
+    anchor.row < focus.row || (anchor.row === focus.row && anchor.col <= focus.col)
+      ? [anchor, focus]
+      : [focus, anchor]
+  return { from, to }
+}
+
+function span(row, from, to) {
+  if (row < from.row || row > to.row) return null
+  return {
+    start: row === from.row ? from.col : 0,
+    end: row === to.row ? to.col + 1 : Infinity
+  }
+}
+
+function walk(line, start, end) {
+  let col = 0
+  let text = ''
+  let painted = ''
+  let on = false
+  for (const cell of cells(line)) {
+    if (cell.esc) {
+      painted += cell.esc
+      if (on && RESETS.has(cell.esc)) painted += REVERSE
+      continue
+    }
+    const inside = col >= start && col < end
+    if (inside && !on) painted += REVERSE
+    if (!inside && on) painted += REVERSE_OFF
+    on = inside
+    if (inside) text += cell.ch
+    painted += cell.ch
+    col += cell.w
+  }
+  if (on) painted += REVERSE_OFF
+  return { text: text.replace(/ +$/, ''), painted }
+}
+
+export function selectionText(lines, anchor, focus) {
+  const { from, to } = ordered(anchor, focus)
+  const rows = []
+  for (let row = from.row; row <= Math.min(to.row, lines.length - 1); row++) {
+    const at = span(row, from, to)
+    rows.push(walk(lines[row], at.start, at.end).text)
+  }
+  return rows.join('\n').replace(/^\n+|\n+$/g, '')
+}
+
+export function paintSelection(lines, anchor, focus) {
+  const { from, to } = ordered(anchor, focus)
+  return lines.map((line, row) => {
+    const at = span(row, from, to)
+    return at ? walk(line, at.start, at.end).painted : line
+  })
+}

package/tui/lib/setup.mjs

@@ -0,0 +1,109 @@
+// What a skill still needs before it can run, expressed as something the TUI can
+// run for you: an OAuth route becomes /connect, a pasted-token route a /cred
+// stub, anything else its own steps. The routes themselves come from the shared
+// integrations registry, so the TUI and the desktop Settings UI agree on what
+// setting a skill up means.
+import { deriveSetupRoutes } from '../../dist-lib/lib/integrations/index.js'
+
+const STATUS_LABELS = {
+  ready: 'ready',
+  'needs-setup': 'needs setup',
+  disconnected: 'reconnect',
+  outdated: 'update available',
+  failed: 'failed',
+  disabled: 'disabled',
+  unsupported: 'unsupported here',
+  'incompatible-model': 'needs a bigger model'
+}
+
+export function statusLabel(status) {
+  return STATUS_LABELS[status] ?? status ?? 'unknown'
+}
+
+export function isReady(skill) {
+  return skill?.status === 'ready'
+}
+
+export function connectSlug(credentialKey) {
+  return credentialKey
+    .replace(/_access_token$/, '')
+    .replace(/_mcp$/, '')
+    .replaceAll('_', '-')
+}
+
+// Every route a skill exposes, in manifest order. A skill can have more than
+// one way in — Obsidian is either the CLI or a vault folder — and the ones that
+// carry a credential key are also how it is RECONFIGURED later.
+export function setupActions(skill) {
+  return (deriveSetupRoutes(skillEntry(skill)).routes ?? []).map((route) =>
+    routeAction(route, skill)
+  )
+}
+
+// What to offer, and what else there is: `primary` is the first unsatisfied
+// route, preferring one the TUI can run over one that only prints instructions;
+// `others` are the remaining ways in, rendered as a one-line "or …" each.
+export function setupPlan(skill) {
+  const actions = setupActions(skill)
+  const open = actions.filter((action) => !action.satisfied)
+  const primary = open.find((action) => action.command || action.prefill) ?? open[0] ?? null
+  const others = actions.filter((action) => action !== primary)
+  return { primary, others }
+}
+
+export function setupAction(skill) {
+  return setupPlan(skill).primary
+}
+
+// Every route the TUI can run, offered one first. A connected skill keeps
+// these: they are how it is pointed somewhere else (another Obsidian vault,
+// another GitHub token) — a route with a credential key is configuration, not
+// a one-time connect.
+export function configureActions(skill) {
+  const { primary, others } = setupPlan(skill)
+  return [primary, ...others].filter((action) => action?.command || action?.prefill)
+}
+
+function routeAction(route, skill) {
+  const action = {
+    kind: 'steps',
+    label: route.label,
+    description: route.description ?? null,
+    helpUrl: route.helpUrl ?? null,
+    satisfied: route.satisfied === true,
+    steps: route.kind === 'install' ? installSteps(skill) : [...(route.steps ?? [])],
+    command: undefined,
+    prefill: undefined
+  }
+  if (!route.credentialKey) return action
+  if (route.kind === 'oauth') {
+    return { ...action, kind: 'connect', command: `/connect ${connectSlug(route.credentialKey)}` }
+  }
+  return { ...action, kind: 'cred', prefill: `/cred ${route.credentialKey} ` }
+}
+
+function installSteps(skill) {
+  return (skill.install ?? []).map((s) => (s.command ? `${s.label} → ${s.command}` : s.label))
+}
+
+// The engine reports a skill flat (name, status, credentials, …); the route
+// registry reads a catalog entry. `a|b` credential slots list interchangeable
+// keys — each is its own candidate route.
+function skillEntry(skill) {
+  const credentials = (skill.requires?.credentials ?? skill.credentials ?? []).flatMap((slot) =>
+    slot.split('|')
+  )
+  return {
+    metadata: {
+      name: skill.name,
+      description: skill.description,
+      setup: skill.setup,
+      transports: skill.transports,
+      requires: { ...skill.requires, credentials },
+      install: skill.install
+    },
+    content: '',
+    available: isReady(skill),
+    state: skill.status
+  }
+}

package/tui/lib/sidebar.mjs

@@ -0,0 +1,52 @@
+// The chat sidebar's row model: chats under their groups, in the order core
+// presents them (groups first, each chat newest-activity first). Rows are what
+// the pane draws and what its cursor walks; only `chat` rows are selectable.
+
+export const SIDEBAR_COLS = 26
+
+export function sidebarRows(chats, groups, activeId) {
+  const live = [...(chats ?? [])].reverse().filter((chat) => !chat.deletedAt)
+  const rows = []
+  for (const group of groups ?? []) {
+    const held = live.filter((chat) => chat.groupId === group.id)
+    rows.push({ kind: 'group', label: group.name })
+    if (!held.length) rows.push({ kind: 'empty', label: '(empty)' })
+    for (const chat of held) rows.push(chatRow(chat, activeId))
+  }
+  const loose = live.filter((chat) => !chat.groupId)
+  if (loose.length && rows.length) rows.push({ kind: 'group', label: '(ungrouped)' })
+  for (const chat of loose) rows.push(chatRow(chat, activeId))
+  return rows
+}
+
+// The move picker's rows — every group, plus ungrouping, minus the one the chat
+// already sits in.
+export function moveRows(groups, groupId) {
+  const rows = (groups ?? [])
+    .filter((group) => group.id !== groupId)
+    .map((group) => ({ kind: 'target', label: group.name, groupId: group.id }))
+  if (groupId) rows.unshift({ kind: 'target', label: '(no group)', groupId: null })
+  rows.push({ kind: 'new-group', label: 'New group…' })
+  return rows
+}
+
+// The next row the cursor may land on, walking `delta` at a time; the headers
+// and the (empty) placeholders are skipped. Stays put at either end.
+export function nextSelectable(rows, from, delta) {
+  for (let i = from + delta; i >= 0 && i < rows.length; i += delta) {
+    if (selectable(rows[i])) return i
+  }
+  return selectable(rows[from]) ? from : firstSelectable(rows)
+}
+
+export function firstSelectable(rows) {
+  return rows.findIndex(selectable)
+}
+
+export function selectable(row) {
+  return row?.kind === 'chat' || row?.kind === 'target' || row?.kind === 'new-group'
+}
+
+function chatRow(chat, activeId) {
+  return { kind: 'chat', label: chat.title, chatId: chat.id, active: chat.id === activeId }
+}