@qvac/core 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <img src="ducks.png" alt="" width="200">
2
+ <img src="https://raw.githubusercontent.com/tetherto/qvac-core/main/ducks.png" alt="" width="200">
3
3
  </p>
4
4
 
5
5
  <h1 align="center">@qvac/core</h1>
@@ -655,14 +655,15 @@ bun run engine:collabora
655
655
  ```
656
656
 
657
657
  The TUI copies its mesh invite to the clipboard on ctrl+y. On a second machine
658
- (or a second terminal):
658
+ (or a second terminal), start `duck` and join from inside it:
659
659
 
660
- ```sh
661
- duck qvac://mesh/…
660
+ ```
661
+ /join qvac://mesh/…
662
662
  ```
663
663
 
664
- A running TUI moves mesh with `/join qvac://mesh/…` — it retires the mesh it is
665
- on, joins that one, and re-resolves the agent and chat from it.
664
+ That retires the mesh it is on, joins the invited one, and re-resolves the agent
665
+ and chat from it. The engine takes an invite live, so joining never needed to be
666
+ a boot argument.
666
667
 
667
668
  `--headless` brings the same stack up with no TUI: it prints the invite and then
668
669
  streams logs (including the sidecar child's own output, which the TUI drops) to
@@ -683,8 +684,7 @@ same replicated stream: load progress, thinking, tokens, tool approvals
683
684
  ```sh
684
685
  npm test # node + bare suites
685
686
  npm run build:schema # regenerate spec/ from schema/ (bare)
686
- bun run duck # build the TUI sidecar bundle, then run it
687
- bun run duck:warm # run the TUI against the last-built bundle
687
+ bun run duck # run the TUI (no build step)
688
688
  ```
689
689
 
690
690
  The TUI lives in [`tui/`](tui/README.md) and installs as the `duck` command.
@@ -21,6 +21,7 @@ export interface UploadStream<In, Out> extends WatchStream<Out> {
21
21
 
22
22
  // what hrpc hands a duplex handler (its own async iterator hangs - see api/attachments.ts)
23
23
  export interface HandlerFrames<Frame> {
24
+ readonly writeStream?: { readonly destroyed: boolean; readonly destroying: boolean; on(event: 'close', listener: () => void): void; off(event: 'close', listener: () => void): void }
24
25
  on(event: 'data', listener: (frame: Frame) => void): void
25
26
  on(event: 'end', listener: () => void): void
26
27
  on(event: 'error', listener: (err: Error) => void): void
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qvac/core",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "type": "module",
5
5
  "description": "Peer-to-peer AI across your devices",
6
6
  "exports": {
@@ -134,15 +134,15 @@
134
134
  "./suspend-lifecycle": {
135
135
  "types": "./dist-lib/lib/suspend-lifecycle.d.ts",
136
136
  "default": "./dist-lib/lib/suspend-lifecycle.js"
137
- },
138
- "./dist/assistant.cjs": "./dist/assistant.cjs"
137
+ }
138
+ },
139
+ "bin": {
140
+ "duck": "./tui/index.mjs"
139
141
  },
140
142
  "scripts": {
141
- "build:tui": "node tui/build.mjs",
142
143
  "build:splash": "node tui/build-splash.mjs",
143
144
  "build:schema": "bare schema/build.ts",
144
- "duck": "node tui/build.mjs && bare tui/index.mjs",
145
- "duck:warm": "bare tui/index.mjs",
145
+ "duck": "bare tui/index.mjs",
146
146
  "mesh-peer": "bare examples/mesh-peer.mjs",
147
147
  "mesh-lab": "bare examples/mesh-lab.mjs",
148
148
  "test": "npm run test:node && npm run test:bare && npm run test:addons",
@@ -152,7 +152,7 @@
152
152
  "format": "prettier . --write",
153
153
  "lint": "prettier . --check && lunte && tsc --noEmit",
154
154
  "build:bundle": "node scripts/build-bundle.mjs",
155
- "prepack": "node scripts/build-lib.mjs && node scripts/build-bundle.mjs --minify",
155
+ "prepack": "node scripts/build-lib.mjs",
156
156
  "build:lib": "node scripts/build-lib.mjs",
157
157
  "test:addons": "node --test scripts/addon-externals.test.cjs"
158
158
  },
@@ -216,7 +216,8 @@
216
216
  }
217
217
  },
218
218
  "dependencies": {
219
- "@qvac/harness": "^0.2.1",
219
+ "@qvac/harness": "^0.2.4",
220
+ "@qvac/skills": "^0.1.3",
220
221
  "asenion": "^0.1.0",
221
222
  "autobee": "2.6.0",
222
223
  "b4a": "^1.8.1",
@@ -239,10 +240,12 @@
239
240
  "bare-rpc": "^1.3.7",
240
241
  "bare-semver": "^1.1.0",
241
242
  "bare-storage": "^1.1.0",
243
+ "bare-stow": "^0.1.4",
242
244
  "bare-stream": "^2.13.3",
243
245
  "bare-subprocess": "^6.1.0",
244
246
  "bare-supervisor": "^0.1.1",
245
247
  "bare-system-logger": "^1.0.3",
248
+ "bare-tui": "^0.0.3",
246
249
  "bare-url": "^2.4.5",
247
250
  "blind-peer": "^3.10.2",
248
251
  "blind-peering": "^2.7.0",
@@ -267,6 +270,9 @@
267
270
  "protomux-wakeup": "^2.9.0",
268
271
  "rache": "^1.0.0",
269
272
  "ready-guard": "^1.0.0",
273
+ "ready-resource": "^1.2.0",
274
+ "rocksdb-native": "^3.17.4",
275
+ "safety-catch": "^1.0.3",
270
276
  "scope-lock": "^1.2.4",
271
277
  "streamx": "^2.28.0",
272
278
  "suspendify": "^1.7.2",
@@ -283,8 +289,6 @@
283
289
  "bare-pack": "^2.2.1",
284
290
  "bare-runtime": "^1.30.0",
285
291
  "bare-sidecar": "^0.5.2",
286
- "bare-stow": "^0.1.4",
287
- "bare-tui": "^0.0.3",
288
292
  "brittle": "^4.0.2",
289
293
  "holepunch-types": "^0.2.1",
290
294
  "hyperdht": "^6.32.0",
package/tui/README.md ADDED
@@ -0,0 +1,134 @@
1
+ # duck
2
+
3
+ The interactive chat TUI over `@qvac/core` — the real llama.cpp harness (via
4
+ `@qvac/sdk`), the real chunk stream, a real mesh.
5
+
6
+ ## Installation
7
+
8
+ `duck` ships in the `@qvac/core` package, so an install puts it on PATH:
9
+
10
+ ```sh
11
+ npm i -g @qvac/core # duck
12
+ ```
13
+
14
+ In the repo:
15
+
16
+ ```sh
17
+ bun run duck # no build step
18
+ ```
19
+
20
+ `duck` spawns `worker/assistant-sidecar.mjs` — the same entry the desktop app
21
+ stows — and the harness the same way, as files rather than bundles. There is
22
+ nothing to rebuild: every source it runs is read from disk, so an edit to
23
+ `worker/`, `lib/` or the TUI itself takes effect on the next run.
24
+
25
+ A stow bundle is two halves — the JS inlined into it, and the native addons
26
+ offloaded beside it, since dlopen cannot read a path inside a bundle — and it
27
+ earns that split only when the code is relocated away from `node_modules`. The
28
+ desktop and mobile apps do exactly that, and stow their own entries at their own
29
+ build time, from one tree, so their halves cannot disagree. `duck` runs from
30
+ inside `node_modules`, where every addon already sits beside the JS that calls
31
+ it, so a bundle here would only separate a pair that is already together. This
32
+ package published one anyway until 0.1.2, and a `bare-pipe` one patch release
33
+ ahead of the JS calling it hung the sidecar on boot with no error at all.
34
+
35
+ `scripts/build-bundle.mjs` still builds one for anyone who does relocate; it is
36
+ not published.
37
+
38
+ `index.mjs` is the `duck` bin — a `#!/usr/bin/env bare` script, so `bare` has to
39
+ be on PATH (`bare-runtime` puts it in `node_modules/.bin`). `bare-tui` needs
40
+ Bare's native TTY; the TUI will not run under node.
41
+
42
+ ## Usage
43
+
44
+ ```
45
+ duck [--storage <dir>] [--temp] [--headless]
46
+ ```
47
+
48
+ Flags may appear in any order. Joining a mesh is `/join qvac://mesh/…` inside
49
+ the app, not a boot argument.
50
+
51
+ - `--storage <dir>` — a self-contained root (its own corestore and SDK home
52
+ under `<dir>`). `QVAC_STORAGE` is the env fallback.
53
+ - `--temp` — the same, in a throwaway dir. `QVAC_TEMP=1` is the env fallback.
54
+ - `--headless` — brings the same stack up with no TUI: prints the mesh invite,
55
+ then streams logs (including the sidecar child's own output) to stdout until
56
+ ctrl+C. A mesh peer to point other instances at, and the only live view of
57
+ the boot the TUI hides.
58
+
59
+ Storage defaults to the desktop app's release root (`resolveStorage`, i.e.
60
+ `<platform-persistent>/qvac/dev`), so the TUI resumes the same mesh and chats
61
+ the desktop persists there — one at a time (the corestore is single-writer, so
62
+ quit the desktop first) and only across matching Core/schema versions. Models
63
+ stay in the shared global `~/.qvac/models`; `QVAC_ENV` picks another channel.
64
+
65
+ To run alongside another qvac app that already holds the SDK registry lock, use
66
+ an explicit root — it puts the SDK home and its lock on a scratch
67
+ `<dir>/sdk-home`. Models are still shared; `QVAC_MODEL_CACHE_PATH` isolates
68
+ those too.
69
+
70
+ The TUI copies its mesh invite to the clipboard on ctrl+y; a running TUI moves
71
+ mesh with `/join qvac://mesh/…`. See [../docs/tui-commands.md](../docs/tui-commands.md)
72
+ for the full command set.
73
+
74
+ ## Environment
75
+
76
+ | Variable | Effect |
77
+ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
+ | `QVAC_MODEL` | Overrides the demo agent's model — a registry name, or a local path/URL |
79
+ | `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 |
80
+ | `QVAC_IMAGE_MODEL` | Enables the `generate_image`/`edit_image` tools — a catalog choice (`sd2` \| `sdxl` \| `flux2-klein`), or a local diffusion model |
81
+ | `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) |
82
+ | `QVAC_LOG_FILE`, `QVAC_LOG_LEVEL` | Move the log file / pick the level (`debug` \| `info` \| `warn` \| `error`, default `info`) |
83
+ | `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 |
84
+ | `QVAC_INPROCESS=1` | Runs Core and Client in this process, no sidecar — the only topology that can inject a live harness object |
85
+
86
+ ```sh
87
+ QVAC_MODEL=~/.qvac/models/3a65a2a3c6a30a47_Qwen3.5-4B-Q4_K_M.gguf \
88
+ QVAC_MMPROJ=~/.qvac/models/0e037fa9ec5dddcf_Qwen3.5-4B.mmproj-Q8_0.gguf \
89
+ duck
90
+ ```
91
+
92
+ Logs (Core's own lines, and the sidecar child's piped stdout/stderr — the
93
+ llama.cpp and SDK output) go to `<storage.root>/assistant.log`, as they do on
94
+ desktop. Nothing is printed: the TUI owns the tty.
95
+
96
+ ## Layout
97
+
98
+ | Path | Responsibility |
99
+ | ----------- | ------------------------------------------------------------------------------------------ |
100
+ | `index.mjs` | The `duck` bin — CLI, storage resolution, and the two topologies (sidecar, in-process) |
101
+ | `app.mjs` | The TUI itself — state, keys, commands, rendering |
102
+ | `lib/` | Leaf helpers: wrapping, selection, rendering, export, knowledge import, uploads, prebuilds |
103
+
104
+ ## Splash
105
+
106
+ An empty transcript — first boot, and a fresh chat — shows `../ducks.png` as
107
+ half-block truecolor art, centered, with that state's own caption beneath it
108
+ (`starting up…`, `connecting to the mesh…`, `(say hello)`).
109
+
110
+ `lib/splash-art.mjs` is generated and committed; regenerate it when the image
111
+ changes:
112
+
113
+ ```sh
114
+ bun run build:splash
115
+ ```
116
+
117
+ It carries four cuts — 64x32, 48x24, 32x16 and 24x12 cells. `splash()` takes
118
+ the widest that fits the body and falls back to the bare caption when none
119
+ does, so a roomy window gets more of the illustration and a 24-row terminal
120
+ still gets a duck. The ladder tops out well short of a full-screen window: this
121
+ is a splash above the prompt, not a wallpaper.
122
+
123
+ ## Busy words
124
+
125
+ A run with no model progress to report shows a duck-themed gerund instead of
126
+ `thinking…` — `Dabbling…`, `Pondering…`, `Quackompiling…`. The word is a pure
127
+ function of the run id (`lib/busy-words.mjs`), so it holds for that whole run
128
+ rather than flickering on every repaint, and two runs rarely land on the same
129
+ one. States that _do_ have something to report keep saying it (`loading X…`,
130
+ `downloading X: 40%`).
131
+
132
+ ## License
133
+
134
+ Apache-2.0