@qvac/core 0.1.0 → 0.1.2

package/tui/lib/busy-words.mjs

@@ -0,0 +1,64 @@
+// What the busy line says while a run is in flight, in place of `thinking…`.
+// Every word has to read as a mind at work first and a duck second — so the
+// real words here already mean thinking or grinding (Pondering, Brooding,
+// Fathoming, Sifting) and merely happen to be pond-, egg-, or water-flavoured,
+// and the invented ones are a duck noise wrapped around a verb that is plainly
+// work (Quackompiling, Quacksmithing). Things a duck simply does — bobbing,
+// drifting, moulting, honking — are not busy words and do not belong here.
+export const WORDS = [
+  'Angling',
+  'Beakstorming',
+  'Bill-shuffling',
+  'Brooding',
+  'Charting',
+  'Dabbling',
+  'Deliberating',
+  'Diving',
+  'Dredging',
+  'Fathoming',
+  'Featherweighing',
+  'Foraging',
+  'Hatching',
+  'Incubating',
+  'Marinating',
+  'Marshalling',
+  'Mulling',
+  'Navigating',
+  'Noodling',
+  'Paddling',
+  'Percolating',
+  'Plotting',
+  'Pondering',
+  'Pondulating',
+  'Preening',
+  'Puzzling',
+  'Quackogitating',
+  'Quackompiling',
+  'Quackrunching',
+  'Quacksmithing',
+  'Quackstorming',
+  'Quackulating',
+  'Ruminating',
+  'Scheming',
+  'Sifting',
+  'Simmering',
+  'Skimming',
+  'Sounding',
+  'Steeping',
+  'Trawling',
+  'Untangling',
+  'Waddlewrangling',
+  'Weighing',
+  'Wrangling'
+]
+
+// Keyed off the run so the word holds for that whole run instead of flickering
+// on every repaint, and so two runs rarely land on the same one. No key (a
+// state with no run behind it) is the plain word.
+export function busyWord(runId) {
+  if (!runId) return 'Thinking…'
+  const key = typeof runId === 'string' ? runId : runId.toString('hex')
+  let hash = 0
+  for (let i = 0; i < key.length; i++) hash = (hash * 31 + key.charCodeAt(i)) >>> 0
+  return `${WORDS[hash % WORDS.length]}…`
+}

package/tui/lib/export.mjs

@@ -0,0 +1,125 @@
+// The transcript as markdown: one section per run, thinking and answer clearly
+// marked so an exported file can be read (and reported on) away from the TUI.
+
+const STATUS = { completed: 'completed', failed: 'failed', canceled: 'canceled' }
+
+function quote(text) {
+  return text
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n')
+}
+
+function json(value) {
+  return ['```json', JSON.stringify(value ?? null, null, 2), '```'].join('\n')
+}
+
+// A model is a registry name or a path/URL to the weights — the file is what
+// identifies the run either way, so the directories never reach the report.
+function modelLabel(model) {
+  return model.split(/[?#]/)[0].split(/[\\/]/).pop() || model
+}
+
+function metricsLine(turn) {
+  const metrics = turn.statusDetail?.metrics
+  if (!metrics) return null
+  const parts = [`${metrics.totalTokens} tokens`]
+  if (metrics.tokensPerSecond) parts.push(`${metrics.tokensPerSecond.toFixed(1)} tok/s`)
+  if (metrics.timeToFirstToken) parts.push(`ttft ${Math.round(metrics.timeToFirstToken)}ms`)
+  if (metrics.cacheTokens) parts.push(`${metrics.cacheTokens} cached`)
+  return `_${parts.join(' · ')}_`
+}
+
+// Retrieval returns CHUNKS, so one document can appear many times over — say
+// how many, and give each its index, score and the text the model actually read.
+function sourcesSection(detail) {
+  const rows = detail.sources ?? []
+  if (!rows.length) return ['### Sources', '', detail.notice ?? '(none)']
+  const documents = new Set(rows.map((source) => source.documentId ?? source.title)).size
+  const chunks = `${rows.length} ${rows.length === 1 ? 'chunk' : 'chunks'}`
+  const from = `${documents} ${documents === 1 ? 'document' : 'documents'}`
+  const lines = [`### Sources — ${chunks} from ${from}`, '']
+  for (const source of rows) {
+    const score = typeof source.score === 'number' ? ` · score ${source.score.toFixed(2)}` : ''
+    lines.push(`- **${source.title}** — chunk ${source.chunkIndex}${score}`)
+    if (source.url) lines.push(`  ${source.url}`)
+    if (source.excerpt) lines.push('', quote(source.excerpt.trim()).replace(/^/gm, '  '), '')
+  }
+  return lines
+}
+
+function segmentSection(segment) {
+  const { type, detail } = segment
+  if (type === 'thinking') return ['### Thinking', '', quote(segment.text.trim())]
+  if (type === 'content') return ['### Answer', '', segment.text.trim()]
+  if (type === 'tool-call') {
+    return [`### Tool call — \`${detail.name}\``, '', json(detail.arguments)]
+  }
+  if (type === 'tool-result') {
+    return [`### Tool result — \`${detail.name}\``, '', json(detail.result)]
+  }
+  if (type === 'attachment') {
+    return [`- **attachment:** ${detail.fileName} (${detail.mimeType}, ${detail.byteLength}B)`]
+  }
+  if (type === 'sources') return sourcesSection(detail)
+  if (type === 'approval-request') {
+    const call = detail.resource
+      ? `${detail.name} → ${detail.resource.kind} ${detail.resource.label}`
+      : `${detail.name}(${JSON.stringify(detail.arguments)})`
+    return [`### Approval — ${detail.status}`, '', call]
+  }
+  return ['### Answer', '', (segment.text ?? '').trim()]
+}
+
+function agentSection(turn, index) {
+  const status = STATUS[turn.status] ?? turn.status ?? 'in flight'
+  const lines = [`## Run ${index} — ${status}`, '']
+  for (const segment of turn.segments) lines.push(...segmentSection(segment), '')
+  if (turn.status === 'failed') lines.push(`> **failed:** ${turn.statusReason ?? 'unknown'}`, '')
+  const metrics = metricsLine(turn)
+  if (metrics) lines.push(metrics, '')
+  return lines
+}
+
+function userSection(turn) {
+  const lines = ['## Prompt', '']
+  for (const segment of turn.segments) {
+    if (segment.type === 'attachment') lines.push(...segmentSection(segment), '')
+    else lines.push((segment.text ?? '').trim(), '')
+  }
+  return lines
+}
+
+// The turn index the export starts at: the nth-from-last run, plus whatever the
+// user said right before it.
+function startOfRuns(turns, runs) {
+  const runAt = []
+  for (const [index, turn] of turns.entries()) {
+    if (turn.from === 'agent' && (turn.segments.length || turn.status)) runAt.push(index)
+  }
+  if (!runAt.length) return -1
+  let start = runAt[Math.max(0, runAt.length - runs)]
+  while (start > 0 && turns[start - 1].from === 'user') start--
+  return start
+}
+
+export function exportMarkdown(turns, runs = 1, meta = {}) {
+  const start = startOfRuns(turns, runs)
+  if (start < 0) return null
+  const lines = [`# ${meta.title ?? 'Chat'}`, '']
+  if (meta.chatId) lines.push(`- **chat:** \`${meta.chatId}\``)
+  if (meta.agentName) lines.push(`- **agent:** ${meta.agentName}`)
+  if (meta.modelName) lines.push(`- **model:** ${modelLabel(meta.modelName)}`)
+  lines.push(`- **exported:** ${new Date(meta.at ?? Date.now()).toISOString()}`, '')
+
+  let index = 0
+  for (const turn of turns.slice(start)) {
+    lines.push('---', '')
+    if (turn.from === 'user') lines.push(...userSection(turn))
+    else lines.push(...agentSection(turn, ++index))
+  }
+  return `${lines
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()}\n`
+}

package/tui/lib/knowledge-command.mjs

@@ -0,0 +1,144 @@
+import b4a from 'b4a'
+import { importKnowledgeDirectory, importKnowledgeFile } from './knowledge-import.mjs'
+import { saveUniqueStream } from './save-file.mjs'
+
+const USAGE =
+  'usage: /knowledge [list] · /knowledge add <file> · /knowledge add-dir <directory> · /knowledge download <n|id> · /knowledge remove <n|id>'
+
+export async function knowledgeCommand(engine, { chatId, saveDir }, input) {
+  try {
+    return { type: 'notice', text: await execute(engine, chatId, saveDir, input) }
+  } catch (error) {
+    return { type: 'run.error', error }
+  }
+}
+
+async function execute(engine, chatId, saveDir, input) {
+  const { action, argument } = parseInput(input)
+  if ((!action || action === 'list') && !argument) {
+    const [{ knowledge }, { statuses }] = await Promise.all([
+      engine.listKnowledge({ chatId }),
+      engine.listIndexing({ chatId })
+    ])
+    return formatKnowledge(sortKnowledge(knowledge ?? []), statuses ?? [])
+  }
+  if (action === 'add' || action === 'add-dir') {
+    if (!argument) return USAGE
+    if (action === 'add') {
+      const added = await importKnowledgeFile(engine, chatId, argument)
+      return `uploaded ${singleLine(added.fileName)} (${added.byteLength}B) · run /knowledge to track indexing`
+    }
+    return formatDirectoryImport(await importKnowledgeDirectory(engine, chatId, argument))
+  }
+
+  const [selector, ...extra] = argument.split(/\s+/)
+  if ((action !== 'download' && action !== 'remove') || !selector || extra.length) return USAGE
+
+  const { knowledge } = await engine.listKnowledge({ chatId })
+  const selected = resolveKnowledge(sortKnowledge(knowledge ?? []), selector)
+  if (selected.error) return selected.error
+  const row = selected.knowledge
+  if (action === 'remove') {
+    await engine.removeKnowledge({ knowledgeId: row.id, at: Date.now() })
+    return `removed ${singleLine(row.fileName)} (${row.id.slice(0, 8)})`
+  }
+
+  const saved = await saveUniqueStream(
+    saveDir,
+    row.fileName,
+    frameData(engine.downloadKnowledge({ blobId: row.blobId }))
+  )
+  if (saved) return `saved ${singleLine(row.fileName)} (${saved.bytesWritten}B) to ${saved.file}`
+  return `not saved: 100 files named ${singleLine(row.fileName)} already exist in ${saveDir}`
+}
+
+function parseInput(input) {
+  const value = input.trim()
+  const separator = value.search(/\s/)
+  if (separator === -1) return { action: value, argument: '' }
+  return {
+    action: value.slice(0, separator),
+    argument: value.slice(separator).trimStart()
+  }
+}
+
+function formatDirectoryImport(result) {
+  if (!result.added.length && !result.failed.length) {
+    return `no supported knowledge files in ${result.directory}`
+  }
+  const lines = [
+    `uploaded ${result.added.length} knowledge file${result.added.length === 1 ? '' : 's'}`
+  ]
+  for (const row of result.added) {
+    lines.push(`   + ${singleLine(row.fileName)} (${row.byteLength}B)`)
+  }
+  for (const row of result.failed) {
+    lines.push(`   ! ${singleLine(row.fileName)} · ${singleLine(row.error)}`)
+  }
+  if (result.skipped.length) {
+    lines.push(
+      `   - skipped ${result.skipped.length} unsupported ${result.skipped.length === 1 ? 'entry' : 'entries'}`
+    )
+  }
+  if (result.added.length) lines.push('run /knowledge to track indexing')
+  return lines.join('\n')
+}
+
+function formatKnowledge(knowledge, statuses) {
+  if (!knowledge.length) return 'no knowledge in this chat'
+  const byKnowledge = new Map()
+  for (const row of statuses) {
+    const rows = byKnowledge.get(row.knowledgeId) ?? []
+    rows.push(row)
+    byKnowledge.set(row.knowledgeId, rows)
+  }
+  return knowledge
+    .map((row, index) => formatKnowledgeRow(row, index, byKnowledge.get(row.id) ?? []))
+    .join('\n')
+}
+
+function formatKnowledgeRow(knowledge, index, statuses) {
+  const name = singleLine(knowledge.fileName) || '(unnamed)'
+  const lines = [`${index + 1}. ${name} (${knowledge.byteLength}B) · ${knowledge.id.slice(0, 8)}`]
+  const sorted = [...statuses].sort((a, b) => a.id.localeCompare(b.id))
+  if (!sorted.length) lines.push('   - not indexed')
+  for (const row of sorted) lines.push(`   - ${formatStatus(row)}`)
+  return lines.join('\n')
+}
+
+function formatStatus(row) {
+  const status = row.status === 'indexing' && !row.claimLive ? 'expired' : row.status
+  let detail = `${status} · artifact ${row.id.slice(0, 8)}`
+  if (row.status === 'indexing' && row.claimLive) {
+    detail += ` · claimed by ${b4a.toString(row.claimedBy, 'hex').slice(0, 8)}`
+  }
+  if (row.status === 'failed' && row.error) detail += ` · ${singleLine(row.error)}`
+  return detail
+}
+
+function sortKnowledge(rows) {
+  return [...rows].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id))
+}
+
+function resolveKnowledge(rows, selector) {
+  const exact = rows.find((row) => row.id === selector)
+  if (exact) return { knowledge: exact }
+  if (/^\d+$/.test(selector)) {
+    const index = Number(selector) - 1
+    return rows[index] ? { knowledge: rows[index] } : { error: `no knowledge #${selector}` }
+  }
+  const matches = rows.filter((row) => row.id.startsWith(selector))
+  if (matches.length === 1) return { knowledge: matches[0] }
+  if (matches.length > 1) return { error: `ambiguous knowledge id: ${selector}` }
+  return { error: `no knowledge matching: ${selector}` }
+}
+
+function singleLine(value) {
+  return String(value).replace(/\s+/g, ' ').trim()
+}
+
+async function* frameData(frames) {
+  for await (const frame of frames) {
+    if (frame.data) yield frame.data
+  }
+}

package/tui/lib/knowledge-import.mjs

@@ -0,0 +1,135 @@
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { RAG_ACCEPT_EXTENSIONS } from '../../dist-lib/lib/core/files/rag/extract/document-types.js'
+import { UPLOAD_FRAME_BYTES, writeFrame } from './upload-frames.mjs'
+const ACCEPTED = new Set(RAG_ACCEPT_EXTENSIONS)
+const MIME_TYPES = new Map([
+  ['.pdf', 'application/pdf'],
+  ['.txt', 'text/plain'],
+  ['.md', 'text/markdown'],
+  ['.markdown', 'text/markdown'],
+  ['.rtf', 'application/rtf'],
+  ['.html', 'text/html'],
+  ['.htm', 'text/html'],
+  ['.xhtml', 'application/xhtml+xml'],
+  ['.log', 'text/plain'],
+  ['.json', 'application/json'],
+  ['.jsonl', 'application/x-ndjson'],
+  ['.csv', 'text/csv'],
+  ['.tsv', 'text/tab-separated-values'],
+  ['.xml', 'application/xml'],
+  ['.yaml', 'application/yaml'],
+  ['.yml', 'application/yaml'],
+  // accepted everywhere: a device without the engine waits for a peer to publish the index
+  ['.docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+  ['.doc', 'application/msword'],
+  ['.odt', 'application/vnd.oasis.opendocument.text']
+])
+
+export async function importKnowledgeFile(engine, chatId, inputPath) {
+  const file = resolvePath(inputPath)
+  const stat = await fs.promises.stat(file)
+  if (!stat.isFile()) throw new Error(`not a file: ${file}`)
+  if (!supported(file)) throw new Error(`unsupported knowledge file: ${path.basename(file)}`)
+  return upload(engine, chatId, file, stat.size)
+}
+
+export async function importKnowledgeDirectory(engine, chatId, inputPath) {
+  const directory = resolvePath(inputPath)
+  const stat = await fs.promises.stat(directory)
+  if (!stat.isDirectory()) throw new Error(`not a directory: ${directory}`)
+
+  const added = []
+  const failed = []
+  const skipped = []
+  const names = (await fs.promises.readdir(directory)).sort()
+  for (const name of names) {
+    const file = path.join(directory, name)
+    let fileStat
+    try {
+      fileStat = await fs.promises.lstat(file)
+    } catch (error) {
+      failed.push({ fileName: name, error: errorMessage(error) })
+      continue
+    }
+    if (!fileStat.isFile() || !supported(file)) {
+      skipped.push(name)
+      continue
+    }
+    try {
+      added.push(await upload(engine, chatId, file, fileStat.size))
+    } catch (error) {
+      failed.push({ fileName: name, error: errorMessage(error) })
+    }
+  }
+  return { directory, added, failed, skipped }
+}
+
+function resolvePath(input) {
+  const value = input.trim()
+  if (value.startsWith('file://')) return fileURLToPath(value)
+  if (value === '~') return os.homedir()
+  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2))
+  return path.resolve(value)
+}
+
+function supported(file) {
+  return ACCEPTED.has(path.extname(file).toLowerCase())
+}
+
+async function upload(engine, chatId, file, byteLength) {
+  const fileName = path.basename(file)
+  const extension = path.extname(file).toLowerCase()
+  const stream = engine.uploadKnowledge()
+  let responseError = null
+  const response = readFinal(stream).catch((error) => {
+    responseError = error
+    safeDestroy(stream)
+    return null
+  })
+  const source = fs.createReadStream(file, { highWaterMark: UPLOAD_FRAME_BYTES })
+
+  try {
+    const metadataWritten = await writeFrame(stream, {
+      chatId,
+      fileName,
+      mimeType: MIME_TYPES.get(extension) ?? 'application/octet-stream',
+      totalBytes: byteLength
+    })
+    if (!metadataWritten) throw responseError ?? new Error('knowledge upload closed while writing')
+    for await (const data of source) {
+      if (responseError) throw responseError
+      const dataWritten = await writeFrame(stream, { data })
+      if (!dataWritten) throw responseError ?? new Error('knowledge upload closed while writing')
+    }
+    stream.end()
+    const final = await response
+    if (responseError) throw responseError
+    if (!final?.knowledge) throw new Error('knowledge upload ended without a knowledge row')
+    return { fileName, byteLength, knowledge: final.knowledge }
+  } catch (error) {
+    source.destroy()
+    safeDestroy(stream)
+    throw error
+  }
+}
+
+async function readFinal(stream) {
+  let final = null
+  for await (const frame of stream) final = frame
+  return final
+}
+
+function safeDestroy(stream) {
+  try {
+    stream.destroy()
+  } catch {
+    // Cleanup must not replace the file or transport error.
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/tui/lib/prebuilds.mjs

@@ -0,0 +1,81 @@
+// A stowed bundle carries its JS inline but NOT its native addons: bare-stow
+// offloads every `.bare` to real files beside the bundle (its collectOffloaded
+// writes them relative to the bundle's own directory) because dlopen cannot
+// read a path inside a bundle. scripts/build-bundle.mjs deliberately leaves
+// that forest out of the published tarball — it is per-host binaries the
+// consumer's node_modules already carries — and ships
+// dist/prebuilds-manifest.json naming what to put back.
+//
+// Putting it back is what this does, and it is why `duck` can run the same
+// dist/assistant.bundle the desktop app ships. A repo build leaves the real
+// forest in dist/node_modules, so every link is already there and this costs
+// one readdir; a published install has the manifest and nothing else.
+import fs from 'bare-fs'
+import os from 'bare-os'
+import path from 'path'
+
+const HOST = `${os.platform()}-${os.arch()}`
+
+// Only this machine's prebuilds — the manifest names all six hosts the bundle
+// was built to serve, and the other five are dead weight on a consumer's disk.
+export function ensurePrebuilds(bundle) {
+  const dir = path.dirname(bundle)
+  const manifest = path.join(dir, 'prebuilds-manifest.json')
+  if (!fs.existsSync(manifest)) return
+  const { packages } = JSON.parse(fs.readFileSync(manifest, 'utf8'))
+  const missing = []
+  for (const [pkgPath, hosts] of Object.entries(packages)) {
+    if (!hosts.includes(HOST)) continue
+    const dest = path.join(dir, 'node_modules', pkgPath, 'prebuilds', HOST)
+    if (fs.existsSync(dest)) continue
+    const source = resolvePrebuilds(dir, pkgPath)
+    if (source === null) {
+      missing.push(pkgPath)
+      continue
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    place(source, dest)
+  }
+  // A missing addon is a model load that fails much later with nothing pointing
+  // here, so refuse to spawn instead.
+  if (missing.length > 0) {
+    throw new Error(
+      `prebuilds for ${HOST} not found in node_modules: ${missing.join(', ')} — ` +
+        'reinstall the package (a partial install cannot serve the assistant bundle)'
+    )
+  }
+}
+
+// The same upward walk bare's own resolver does, so a nested manifest key
+// (bare-tty/node_modules/bare-signals) finds the exact copy it names before the
+// hoisted one. That precedence is the whole point: bare-signals is installed
+// twice at different major versions, and linking the nested slot to the hoisted
+// binary loads an addon whose ABI its JS does not match — the failure reads as
+// the addon's constants being undefined, nowhere near here.
+//
+// `from` itself is skipped because its node_modules IS the forest being built:
+// searching it would resolve a key to a link this same run just made, which is
+// how the hoisted binary reached the nested slot in the first place.
+function resolvePrebuilds(from, pkgPath) {
+  const nested = pkgPath.lastIndexOf('node_modules/')
+  const candidates =
+    nested === -1 ? [pkgPath] : [pkgPath, pkgPath.slice(nested + 'node_modules/'.length)]
+  for (let dir = path.dirname(from); ; dir = path.dirname(dir)) {
+    for (const candidate of candidates) {
+      const prebuilds = path.join(dir, 'node_modules', candidate, 'prebuilds', HOST)
+      if (fs.existsSync(prebuilds)) return prebuilds
+    }
+    if (dir === path.dirname(dir)) return null
+  }
+}
+
+// A link keeps one copy of each addon on disk and makes the forest free to
+// rebuild; a filesystem that refuses one (Windows without the privilege, a
+// crossed mount) still gets a working forest, just a fatter one.
+function place(source, dest) {
+  try {
+    fs.symlinkSync(source, dest, os.platform() === 'win32' ? 'junction' : 'dir')
+  } catch {
+    fs.cpSync(source, dest, { recursive: true })
+  }
+}

package/tui/lib/projection-env.mjs

@@ -0,0 +1,24 @@
+// QVAC_MMPROJ: one mmproj for every model, or per-model pairs
+// "model=mmproj,model2=mmproj2" (keys match the agent's model name/path)
+export function parseProjectionEnv(value) {
+  if (!value) return undefined
+  const eq = value.indexOf('=')
+  if (eq < 0) return value
+  const scheme = value.indexOf('://')
+  // '=' appearing only inside a URL (…?token=x) is one global source, not pairs
+  if (scheme >= 0 && scheme < eq) return value
+  const map = {}
+  let key = null
+  for (const segment of value.split(',')) {
+    const i = segment.indexOf('=')
+    if (i > 0) {
+      key = segment.slice(0, i).trim()
+      map[key] = segment.slice(i + 1).trim()
+    } else if (key) {
+      // no '=' means the comma belonged to the previous value (a url like
+      // …?token=a,b); a comma followed by k=v stays ambiguous and unsupported
+      map[key] += ',' + segment.trim()
+    }
+  }
+  return map
+}