@qvac/core 0.1.0 → 0.1.2

package/dist-lib/schema/helpers.d.ts

@@ -0,0 +1,28 @@
+// Hand-written declarations for the generated schema/helpers.js. assistant's own
+// tsconfig uses allowJs + checkJs:false, but strict consumers (app-runtime,
+// mobile) without allowJs need these types to import the module without TS7016.
+// The `*Map` helpers are hyperdb map-reduce emitters: they return an array of
+// plain record rows (e.g. `[{ chatId, type, seq }]`), never a Map. Rows stay
+// `Record<string, any>` to match the previously-inferred shape and keep existing
+// .ts callers permissive.
+export function chunkTypeOrdinal(type: string): number
+export function chunksByTypeMap(record: any): ReadonlyArray<Record<string, any>>
+export function activeAgentsMap(record: any): ReadonlyArray<Record<string, any>>
+export function activeChatsMap(record: any): ReadonlyArray<Record<string, any>>
+export function activeChatsByAgentMap(record: any): ReadonlyArray<Record<string, any>>
+export function activeChatGroupsMap(record: any): ReadonlyArray<Record<string, any>>
+export function activeKnowledgeByChatMap(record: any): ReadonlyArray<Record<string, any>>
+export function activeToolConfigsByAgentMap(record: any): ReadonlyArray<Record<string, any>>
+export function toolActivityByAgentMap(record: any): ReadonlyArray<Record<string, any>>
+export function runRequestsMap(record: any): ReadonlyArray<Record<string, any>>
+export const MEDIA_KINDS: readonly ['audio', 'image', 'video', 'other']
+export const AUDIO_EXTENSIONS: readonly string[]
+export function mediaKindOf(
+  mimeType?: string,
+  fileName?: string
+): 'audio' | 'image' | 'video' | 'other'
+export function mediaKindOrdinal(kind: string): number
+export function attachmentsByMediaKindMap(record: any): ReadonlyArray<Record<string, any>>
+export function attachmentsByMediaKindOriginMap(record: any): ReadonlyArray<Record<string, any>>
+export function historyChunksMap(record: any): ReadonlyArray<Record<string, any>>
+export function liveWritersByMostRecentMap(record: any): ReadonlyArray<Record<string, any>>

package/dist-lib/schema/helpers.js

@@ -0,0 +1,176 @@
+// imported by the generated spec at runtime (dbns.require embeds a relative path) — stays plain .js
+const historyChunkTypes = ['user-message', 'run-request', 'content', 'attachment', 'compaction']
+
+// index keys hold the ordinal, kept in sync by hand with CHUNK_TYPES order in content.ts
+export function chunkTypeOrdinal(type) {
+  switch (type) {
+    case 'user-message':
+      return 1
+    case 'content':
+      return 2
+    case 'thinking':
+      return 3
+    case 'tool-call':
+      return 4
+    case 'tool-result':
+      return 5
+    case 'attachment':
+      return 6
+    case 'approval-request':
+      return 7
+    case 'run-status':
+      return 8
+    case 'run-request':
+      return 9
+    case 'sources':
+      return 10
+    case 'compaction':
+      return 11
+    default:
+      throw new Error('Unknown chunk type: ' + type)
+  }
+}
+
+export function chunksByTypeMap(record) {
+  if (record.type === undefined) return []
+  return [{ chatId: record.chatId, type: chunkTypeOrdinal(record.type), seq: record.seq }]
+}
+
+export function activeAgentsMap(record) {
+  if (record.deletedAt) return []
+  return [{ createdAt: record.createdAt }]
+}
+
+export function activeChatsMap(record) {
+  if (record.deletedAt) return []
+  return [{ createdAt: record.createdAt }]
+}
+
+export function activeChatGroupsMap(record) {
+  if (record.deletedAt) return []
+  return [{ createdAt: record.createdAt }]
+}
+
+export function activeChatsByAgentMap(record) {
+  if (record.deletedAt) return []
+  return [{ agentId: record.agentId, createdAt: record.createdAt }]
+}
+
+export function activeKnowledgeByChatMap(record) {
+  if (record.deletedAt || !record.chatId) return []
+  return [{ chatId: record.chatId }]
+}
+
+export function activeToolConfigsByAgentMap(record) {
+  if (record.deletedAt) return []
+  return [{ agentId: record.agentId }]
+}
+
+// append-only tool-call log keyed by agent then apply-assigned seq — one range query lists an
+// agent's whole activity across every chat and device, in a peer-consistent order (seq, not wall
+// clock). No tombstone filter: activity is immutable history.
+export function toolActivityByAgentMap(record) {
+  if (!record.agentId) return []
+  return [{ agentId: record.agentId, seq: record.seq }]
+}
+
+export function runRequestsMap(record) {
+  if (record.type !== 'run-request') return []
+  return [{ chatId: record.chatId, seq: record.seq }]
+}
+
+// media kinds for the attachments-by-media-kind index. The ordinal rides in the key as a plain
+// uint (same pattern as chunksByTypeMap); MEDIA_KINDS is the name↔ordinal source of truth, and
+// the wire media-kind enum in engine.ts is registered from this same array so the two never drift.
+export const MEDIA_KINDS = ['audio', 'image', 'video', 'other']
+
+// `.mp4` is deliberately audio, not video: audio recordings ship in the mp4 container and are
+// transcribed from their audio track (parity with isAudioAttachment). audio-attachment.ts derives
+// isAudioAttachment from mediaKindOf, so this list is the one source of truth for "what is audio".
+export const AUDIO_EXTENSIONS = ['.m4a', '.mp3', '.wav', '.ogg', '.flac', '.aac', '.mp4']
+const IMAGE_EXTENSIONS = [
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.bmp',
+  '.svg',
+  '.heic',
+  '.heif',
+  '.avif'
+]
+const VIDEO_EXTENSIONS = ['.mov', '.webm', '.mkv', '.avi', '.m4v']
+
+function endsWithAny(name, extensions) {
+  return extensions.some((extension) => name.endsWith(extension))
+}
+
+// classify an attachment by mime first, then filename extension. Broad by design so a generated
+// `audio/wav` and a user `recording.m4a` both land under 'audio'.
+export function mediaKindOf(mimeType, fileName) {
+  const mime = (mimeType || '').toLowerCase()
+  const name = (fileName || '').toLowerCase()
+  if (mime.startsWith('audio/') || endsWithAny(name, AUDIO_EXTENSIONS)) return 'audio'
+  if (mime.startsWith('image/') || endsWithAny(name, IMAGE_EXTENSIONS)) return 'image'
+  if (mime.startsWith('video/') || endsWithAny(name, VIDEO_EXTENSIONS)) return 'video'
+  return 'other'
+}
+
+export function mediaKindOrdinal(kind) {
+  const ordinal = MEDIA_KINDS.indexOf(kind)
+  if (ordinal === -1) throw new Error('Unknown media kind: ' + kind)
+  return ordinal + 1
+}
+
+// every non-deleted attachment chunk, keyed by media kind then createdAt — NOT chatId-prefixed,
+// so one range query lists all audio (uploaded or generated) across every chat in the mesh. Drops
+// non-attachment chunks and tombstoned attachments so a gallery never scans-and-filters.
+export function attachmentsByMediaKindMap(record) {
+  if (record.type !== 'attachment') return []
+  const attachment = record.attachment
+  if (!attachment || attachment.deletedAt) return []
+  return [
+    {
+      mediaKind: mediaKindOrdinal(mediaKindOf(attachment.mimeType, attachment.fileName)),
+      createdAt: record.createdAt
+    }
+  ]
+}
+
+// generated tool output always carries a runId; a user upload never does (attachment-knowledge.ts
+// only routes runId-less uploads to knowledge). So runId presence IS the origin, kept out of the
+// key as a plain 0/1 uint the way mediaKind is.
+function attachmentGenerated(record) {
+  return record.runId ? 1 : 0
+}
+
+// the same attachments as attachmentsByMediaKindMap, but with origin (generated vs uploaded) folded
+// into the key so "only generated audio" / "only uploaded audio" is a range query, not a post-filter.
+export function attachmentsByMediaKindOriginMap(record) {
+  if (record.type !== 'attachment') return []
+  const attachment = record.attachment
+  if (!attachment || attachment.deletedAt) return []
+  return [
+    {
+      mediaKind: mediaKindOrdinal(mediaKindOf(attachment.mimeType, attachment.fileName)),
+      generated: attachmentGenerated(record),
+      createdAt: record.createdAt
+    }
+  ]
+}
+
+export function devicesByWriterKeyMap(record) {
+  if (!record.writerKey) return []
+  return [{ writerKey: record.writerKey }]
+}
+
+export function historyChunksMap(record) {
+  if (!historyChunkTypes.includes(record.type)) return []
+  return [{ chatId: record.chatId, seq: record.seq }]
+}
+
+export function liveWritersByMostRecentMap(record) {
+  if (record.revoked) return []
+  return [{ clock: record.clock }]
+}

package/dist-lib/schema/vendor.d.ts

@@ -0,0 +1,5 @@
+// these builder packages ship no types — blank ambient modules, schema-authoring-time only
+declare module 'hrpc'
+declare module 'hyperdispatch'
+declare module 'hyperschema'
+declare module 'hyperdb/builder'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Peer-to-peer AI across your devices",
   "exports": {
@@ -69,6 +69,10 @@
       "default": "./dist-lib/client.js"
     },
     "./capabilities": "./dist-lib/spec/capabilities.d.ts",
+    "./wire-codec": {
+      "types": "./dist-lib/spec/hrpc/messages.d.ts",
+      "default": "./dist-lib/spec/hrpc/messages.js"
+    },
     "./log": {
       "types": "./dist-lib/lib/log.d.ts",
       "default": "./dist-lib/lib/log.js"
@@ -133,11 +137,13 @@
     },
     "./dist/assistant.cjs": "./dist/assistant.cjs"
   },
+  "bin": {
+    "duck": "./tui/index.mjs"
+  },
   "scripts": {
-    "build:tui": "node tui/build.mjs",
     "build:splash": "node tui/build-splash.mjs",
     "build:schema": "bare schema/build.ts",
-    "duck": "node tui/build.mjs && bare tui/index.mjs",
+    "duck": "node scripts/build-bundle.mjs && bare tui/index.mjs",
     "duck:warm": "bare tui/index.mjs",
     "mesh-peer": "bare examples/mesh-peer.mjs",
     "mesh-lab": "bare examples/mesh-lab.mjs",
@@ -213,6 +219,7 @@
   },
   "dependencies": {
     "@qvac/harness": "^0.2.1",
+    "@qvac/skills": "^0.1.3",
     "asenion": "^0.1.0",
     "autobee": "2.6.0",
     "b4a": "^1.8.1",
@@ -239,6 +246,7 @@
     "bare-subprocess": "^6.1.0",
     "bare-supervisor": "^0.1.1",
     "bare-system-logger": "^1.0.3",
+    "bare-tui": "^0.0.3",
     "bare-url": "^2.4.5",
     "blind-peer": "^3.10.2",
     "blind-peering": "^2.7.0",
@@ -280,7 +288,6 @@
     "bare-runtime": "^1.30.0",
     "bare-sidecar": "^0.5.2",
     "bare-stow": "^0.1.4",
-    "bare-tui": "^0.0.3",
     "brittle": "^4.0.2",
     "holepunch-types": "^0.2.1",
     "hyperdht": "^6.32.0",

package/tui/README.md

@@ -0,0 +1,133 @@
+# duck
+
+The interactive chat TUI over `@qvac/core` — the real llama.cpp harness (via
+`@qvac/sdk`), the real chunk stream, a real mesh.
+
+## Installation
+
+`duck` ships in the `@qvac/core` package, so an install puts it on PATH:
+
+```sh
+npm i -g @qvac/core   # duck
+```
+
+In the repo:
+
+```sh
+bun run duck        # build the assistant bundle, then run
+bun run duck:warm   # reuse the last-built bundle
+```
+
+`duck` runs the SAME `dist/assistant.bundle` the desktop app ships — the stow of
+`worker/assistant-sidecar.mjs` that `scripts/build-bundle.mjs` builds. `bun run
+duck` rebuilds it first, because a stale bundle decodes with the old wire format
+and dies on the first call whose encoding changed; a freshly written bundle also
+pays a one-time cold start on its first spawn (OS page-cache miss + the
+platform's security assessment of the new binary and its native addons). The TUI
+host (`index.mjs`, `app.mjs`) is not in that bundle, so while iterating on the
+TUI use `duck:warm`. Rebuild after changing any `worker/`, wire, or `lib/`
+source.
+
+The bundle carries its JS but not its native addons: `build-bundle.mjs` offloads
+those beside the bundle and leaves the forest out of the tarball, shipping
+`dist/prebuilds-manifest.json` instead. `lib/prebuilds.mjs` links this host's
+addons back into place from the installed `node_modules` on first run — which is
+why an installed `duck` needs no postinstall step.
+
+`index.mjs` is the `duck` bin — a `#!/usr/bin/env bare` script, so `bare` has to
+be on PATH (`bare-runtime` puts it in `node_modules/.bin`). `bare-tui` needs
+Bare's native TTY; the TUI will not run under node.
+
+## Usage
+
+```
+duck [--storage <dir>] [--temp] [--headless]
+```
+
+Flags may appear in any order. Joining a mesh is `/join qvac://mesh/…` inside
+the app, not a boot argument.
+
+- `--storage <dir>` — a self-contained root (its own corestore and SDK home
+  under `<dir>`). `QVAC_STORAGE` is the env fallback.
+- `--temp` — the same, in a throwaway dir. `QVAC_TEMP=1` is the env fallback.
+- `--headless` — brings the same stack up with no TUI: prints the mesh invite,
+  then streams logs (including the sidecar child's own output) to stdout until
+  ctrl+C. A mesh peer to point other instances at, and the only live view of
+  the boot the TUI hides.
+
+Storage defaults to the desktop app's release root (`resolveStorage`, i.e.
+`<platform-persistent>/qvac/dev`), so the TUI resumes the same mesh and chats
+the desktop persists there — one at a time (the corestore is single-writer, so
+quit the desktop first) and only across matching Core/schema versions. Models
+stay in the shared global `~/.qvac/models`; `QVAC_ENV` picks another channel.
+
+To run alongside another qvac app that already holds the SDK registry lock, use
+an explicit root — it puts the SDK home and its lock on a scratch
+`<dir>/sdk-home`. Models are still shared; `QVAC_MODEL_CACHE_PATH` isolates
+those too.
+
+The TUI copies its mesh invite to the clipboard on ctrl+y; a running TUI moves
+mesh with `/join qvac://mesh/…`. See [../docs/tui-commands.md](../docs/tui-commands.md)
+for the full command set.
+
+## Environment
+
+| Variable                                                    | Effect                                                                                                                                                                                               |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `QVAC_MODEL`                                                | Overrides the demo agent's model — a registry name, or a local path/URL                                                                                                                              |
+| `QVAC_MMPROJ`                                               | Pairs models with their mmproj projections so ctrl+V'd images reach the model natively. One value applies to every model; `model=mmproj,model2=mmproj2` pairs are per-model. `QVAC_INPROCESS=1` only |
+| `QVAC_IMAGE_MODEL`                                          | Enables the `generate_image`/`edit_image` tools — a catalog choice (`sd2` \| `sdxl` \| `flux2-klein`), or a local diffusion model                                                                    |
+| `QVAC_IMAGE_LLM`, `QVAC_IMAGE_VAE`, `QVAC_IMAGE_PREDICTION` | FLUX.2 is a companion set: the Qwen3 text encoder, the VAE, and `flux2_flow` (required for img2img)                                                                                                  |
+| `QVAC_LOG_FILE`, `QVAC_LOG_LEVEL`                           | Move the log file / pick the level (`debug` \| `info` \| `warn` \| `error`, default `info`)                                                                                                          |
+| `QVAC_BOOT_TIMING=1`                                        | Prints the total connect time after the TUI exits. Per-stage stamps exist only under `QVAC_INPROCESS=1` — the shared assistant sidecar carries no boot timer                                         |
+| `QVAC_INPROCESS=1`                                          | Runs Core and Client in this process, no sidecar — the only topology that can inject a live harness object                                                                                           |
+
+```sh
+QVAC_MODEL=~/.qvac/models/3a65a2a3c6a30a47_Qwen3.5-4B-Q4_K_M.gguf \
+QVAC_MMPROJ=~/.qvac/models/0e037fa9ec5dddcf_Qwen3.5-4B.mmproj-Q8_0.gguf \
+duck
+```
+
+Logs (Core's own lines, and the sidecar child's piped stdout/stderr — the
+llama.cpp and SDK output) go to `<storage.root>/assistant.log`, as they do on
+desktop. Nothing is printed: the TUI owns the tty.
+
+## Layout
+
+| Path        | Responsibility                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------ |
+| `index.mjs` | The `duck` bin — CLI, storage resolution, and the two topologies (sidecar, in-process)     |
+| `app.mjs`   | The TUI itself — state, keys, commands, rendering                                          |
+| `lib/`      | Leaf helpers: wrapping, selection, rendering, export, knowledge import, uploads, prebuilds |
+
+## Splash
+
+An empty transcript — first boot, and a fresh chat — shows `../ducks.png` as
+half-block truecolor art, centered, with that state's own caption beneath it
+(`starting up…`, `connecting to the mesh…`, `(say hello)`).
+
+`lib/splash-art.mjs` is generated and committed; regenerate it when the image
+changes:
+
+```sh
+bun run build:splash
+```
+
+It carries four cuts — 64x32, 48x24, 32x16 and 24x12 cells. `splash()` takes
+the widest that fits the body and falls back to the bare caption when none
+does, so a roomy window gets more of the illustration and a 24-row terminal
+still gets a duck. The ladder tops out well short of a full-screen window: this
+is a splash above the prompt, not a wallpaper.
+
+## Busy words
+
+A run with no model progress to report shows a duck-themed gerund instead of
+`thinking…` — `Dabbling…`, `Pondering…`, `Quackompiling…`. The word is a pure
+function of the run id (`lib/busy-words.mjs`), so it holds for that whole run
+rather than flickering on every repaint, and two runs rarely land on the same
+one. States that _do_ have something to report keep saying it (`loading X…`,
+`downloading X: 40%`).
+
+## License
+
+Apache-2.0