@qvac/core 1.0.0-rc.5 → 1.0.0-rc.6

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.
Files changed (108) hide show
  1. package/CHANGELOG.md +43 -2
  2. package/README.md +55 -4
  3. package/dist-lib/lib/api/agents.d.ts +2 -1
  4. package/dist-lib/lib/api/agents.js +5 -1
  5. package/dist-lib/lib/api/app-config.d.ts +3 -0
  6. package/dist-lib/lib/api/app-config.js +20 -0
  7. package/dist-lib/lib/api/device-routes.d.ts +1 -1
  8. package/dist-lib/lib/api/device-routes.js +3 -1
  9. package/dist-lib/lib/api/index.js +2 -1
  10. package/dist-lib/lib/api/projects.js +3 -4
  11. package/dist-lib/lib/api/served.d.ts +2 -2
  12. package/dist-lib/lib/api/served.js +24 -1
  13. package/dist-lib/lib/assistant/harness.d.ts +3 -0
  14. package/dist-lib/lib/assistant/history.js +14 -2
  15. package/dist-lib/lib/assistant/message.d.ts +1 -0
  16. package/dist-lib/lib/assistant/model-round.d.ts +3 -0
  17. package/dist-lib/lib/assistant/model-round.js +16 -2
  18. package/dist-lib/lib/assistant/round-host.d.ts +2 -0
  19. package/dist-lib/lib/assistant/round-host.js +8 -0
  20. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  21. package/dist-lib/lib/assistant-tree.js +4 -2
  22. package/dist-lib/lib/assistant.d.ts +11 -1
  23. package/dist-lib/lib/assistant.js +115 -8
  24. package/dist-lib/lib/client.js +4 -1
  25. package/dist-lib/lib/core/agent-copies.js +2 -1
  26. package/dist-lib/lib/core/agent-hosting.js +9 -4
  27. package/dist-lib/lib/core/agent.js +2 -1
  28. package/dist-lib/lib/core/chat-copy.d.ts +1 -0
  29. package/dist-lib/lib/core/chat-copy.js +13 -2
  30. package/dist-lib/lib/core/chat.d.ts +0 -1
  31. package/dist-lib/lib/core/chat.js +0 -3
  32. package/dist-lib/lib/core/collections.d.ts +7 -7
  33. package/dist-lib/lib/core/collections.js +7 -7
  34. package/dist-lib/lib/core/contract/project-device-keys.d.ts +4 -2
  35. package/dist-lib/lib/core/contract/project-device-keys.js +12 -12
  36. package/dist-lib/lib/core/contract/project-host-keys.d.ts +5 -3
  37. package/dist-lib/lib/core/contract/project-host-keys.js +22 -11
  38. package/dist-lib/lib/core/contract/projects.d.ts +4 -2
  39. package/dist-lib/lib/core/contract/projects.js +29 -17
  40. package/dist-lib/lib/core/deleted-agent-runs.d.ts +1 -0
  41. package/dist-lib/lib/core/deleted-agent-runs.js +22 -11
  42. package/dist-lib/lib/core/helpers/index.d.ts +1 -1
  43. package/dist-lib/lib/core/helpers/index.js +2 -2
  44. package/dist-lib/lib/core/mesh.d.ts +1 -0
  45. package/dist-lib/lib/core/mesh.js +4 -4
  46. package/dist-lib/lib/core/project-keys.d.ts +5 -2
  47. package/dist-lib/lib/core/project-keys.js +15 -6
  48. package/dist-lib/lib/core/sync/index.js +5 -5
  49. package/dist-lib/lib/core.d.ts +2 -0
  50. package/dist-lib/lib/core.js +102 -25
  51. package/dist-lib/lib/kv-cache-ledger.d.ts +22 -0
  52. package/dist-lib/lib/kv-cache-ledger.js +72 -0
  53. package/dist-lib/lib/kv-cache-retention.d.ts +1 -0
  54. package/dist-lib/lib/kv-cache-retention.js +5 -2
  55. package/dist-lib/lib/model-memory-cap.d.ts +3 -0
  56. package/dist-lib/lib/model-memory-cap.js +15 -6
  57. package/dist-lib/lib/run-replay.d.ts +3 -2
  58. package/dist-lib/lib/run-replay.js +16 -5
  59. package/dist-lib/lib/run-transcript.js +1 -1
  60. package/dist-lib/schema/engine.js +54 -1
  61. package/dist-lib/schema/qvac.js +62 -1
  62. package/dist-lib/spec/bind.js +3 -0
  63. package/dist-lib/spec/calls.js +1 -0
  64. package/dist-lib/spec/capabilities.d.ts +2 -0
  65. package/dist-lib/spec/hrpc/hrpc.json +13 -0
  66. package/dist-lib/spec/hrpc/index.js +15 -3
  67. package/dist-lib/spec/hrpc/messages.js +253 -3
  68. package/dist-lib/spec/hyperschema/index.js +253 -3
  69. package/dist-lib/spec/hyperschema/schema.json +187 -0
  70. package/dist-lib/spec/hyperschema/types.d.ts +33 -0
  71. package/dist-lib/spec/mesh/hyperdb/db.json +110 -0
  72. package/dist-lib/spec/mesh/hyperdb/index.js +498 -2
  73. package/dist-lib/spec/mesh/hyperdb/messages.js +865 -410
  74. package/dist-lib/spec/mesh/hyperdispatch/messages.js +244 -3
  75. package/dist-lib/spec/mesh/hyperschema/index.js +244 -3
  76. package/dist-lib/spec/mesh/hyperschema/schema.json +155 -0
  77. package/dist-lib/spec/mesh/hyperschema/types.d.ts +37 -0
  78. package/package.json +27 -11
  79. package/tui/README.md +190 -0
  80. package/tui/app.mjs +8247 -0
  81. package/tui/boot.mjs +159 -0
  82. package/tui/index.mjs +89 -0
  83. package/tui/lib/boot-timing.mjs +41 -0
  84. package/tui/lib/busy-words.mjs +116 -0
  85. package/tui/lib/connect-sheet.mjs +350 -0
  86. package/tui/lib/device-target.mjs +64 -0
  87. package/tui/lib/export.mjs +194 -0
  88. package/tui/lib/folders-command.mjs +84 -0
  89. package/tui/lib/fork-command.mjs +43 -0
  90. package/tui/lib/knowledge-command.mjs +190 -0
  91. package/tui/lib/knowledge-import.mjs +153 -0
  92. package/tui/lib/local-path.mjs +21 -0
  93. package/tui/lib/move-command.mjs +17 -0
  94. package/tui/lib/render.mjs +225 -0
  95. package/tui/lib/save-file.mjs +88 -0
  96. package/tui/lib/select.mjs +81 -0
  97. package/tui/lib/selection.mjs +18 -0
  98. package/tui/lib/setup.mjs +135 -0
  99. package/tui/lib/sidebar.mjs +63 -0
  100. package/tui/lib/skill-connect.mjs +145 -0
  101. package/tui/lib/splash-art.mjs +107 -0
  102. package/tui/lib/splash.mjs +18 -0
  103. package/tui/lib/upload-frames.mjs +9 -0
  104. package/tui/lib/usage.mjs +59 -0
  105. package/tui/lib/wrap.mjs +143 -0
  106. package/tui/main.mjs +279 -0
  107. package/tui/plugins.mjs +158 -0
  108. package/worker/assistant-sidecar.mjs +1 -0
@@ -5258,6 +5258,11 @@
5258
5258
  "name": "groupId",
5259
5259
  "type": "string",
5260
5260
  "version": 19
5261
+ },
5262
+ {
5263
+ "name": "seedFingerprint",
5264
+ "type": "fixed32",
5265
+ "version": 19
5261
5266
  }
5262
5267
  ]
5263
5268
  },
@@ -6124,6 +6129,156 @@
6124
6129
  "version": 1
6125
6130
  }
6126
6131
  ]
6132
+ },
6133
+ {
6134
+ "name": "project-host-seal-v1",
6135
+ "namespace": "qvac",
6136
+ "compact": false,
6137
+ "flagsPosition": -1,
6138
+ "fields": [
6139
+ {
6140
+ "name": "projectId",
6141
+ "required": true,
6142
+ "type": "fixed32",
6143
+ "version": 19
6144
+ },
6145
+ {
6146
+ "name": "deviceId",
6147
+ "required": true,
6148
+ "type": "fixed32",
6149
+ "version": 19
6150
+ },
6151
+ {
6152
+ "name": "sealedBy",
6153
+ "required": true,
6154
+ "type": "fixed32",
6155
+ "version": 19
6156
+ },
6157
+ {
6158
+ "name": "agentId",
6159
+ "required": true,
6160
+ "type": "string",
6161
+ "version": 19
6162
+ },
6163
+ {
6164
+ "name": "sealedSeed",
6165
+ "required": true,
6166
+ "type": "buffer",
6167
+ "version": 19
6168
+ }
6169
+ ]
6170
+ },
6171
+ {
6172
+ "name": "project-host-seal",
6173
+ "namespace": "qvac",
6174
+ "framed": false,
6175
+ "versions": [
6176
+ {
6177
+ "type": "@qvac/project-host-seal-v1",
6178
+ "map": null,
6179
+ "version": 1
6180
+ }
6181
+ ]
6182
+ },
6183
+ {
6184
+ "name": "project-member-seal-v1",
6185
+ "namespace": "qvac",
6186
+ "compact": false,
6187
+ "flagsPosition": -1,
6188
+ "fields": [
6189
+ {
6190
+ "name": "projectId",
6191
+ "required": true,
6192
+ "type": "fixed32",
6193
+ "version": 19
6194
+ },
6195
+ {
6196
+ "name": "memberId",
6197
+ "required": true,
6198
+ "type": "fixed32",
6199
+ "version": 19
6200
+ },
6201
+ {
6202
+ "name": "sealedBy",
6203
+ "required": true,
6204
+ "type": "fixed32",
6205
+ "version": 19
6206
+ },
6207
+ {
6208
+ "name": "boxKey",
6209
+ "required": true,
6210
+ "type": "fixed32",
6211
+ "version": 19
6212
+ },
6213
+ {
6214
+ "name": "sealedSeed",
6215
+ "required": true,
6216
+ "type": "buffer",
6217
+ "version": 19
6218
+ }
6219
+ ]
6220
+ },
6221
+ {
6222
+ "name": "project-member-seal",
6223
+ "namespace": "qvac",
6224
+ "framed": false,
6225
+ "versions": [
6226
+ {
6227
+ "type": "@qvac/project-member-seal-v1",
6228
+ "map": null,
6229
+ "version": 1
6230
+ }
6231
+ ]
6232
+ },
6233
+ {
6234
+ "name": "project-device-seal-v1",
6235
+ "namespace": "qvac",
6236
+ "compact": false,
6237
+ "flagsPosition": -1,
6238
+ "fields": [
6239
+ {
6240
+ "name": "projectId",
6241
+ "required": true,
6242
+ "type": "fixed32",
6243
+ "version": 19
6244
+ },
6245
+ {
6246
+ "name": "deviceId",
6247
+ "required": true,
6248
+ "type": "fixed32",
6249
+ "version": 19
6250
+ },
6251
+ {
6252
+ "name": "sealedBy",
6253
+ "required": true,
6254
+ "type": "fixed32",
6255
+ "version": 19
6256
+ },
6257
+ {
6258
+ "name": "memberId",
6259
+ "required": true,
6260
+ "type": "fixed32",
6261
+ "version": 19
6262
+ },
6263
+ {
6264
+ "name": "sealedSeed",
6265
+ "required": true,
6266
+ "type": "buffer",
6267
+ "version": 19
6268
+ }
6269
+ ]
6270
+ },
6271
+ {
6272
+ "name": "project-device-seal",
6273
+ "namespace": "qvac",
6274
+ "framed": false,
6275
+ "versions": [
6276
+ {
6277
+ "type": "@qvac/project-device-seal-v1",
6278
+ "map": null,
6279
+ "version": 1
6280
+ }
6281
+ ]
6127
6282
  }
6128
6283
  ]
6129
6284
  }
@@ -1044,6 +1044,7 @@ export interface QvacProjectV1 {
1044
1044
  createdBy?: Buffer | null
1045
1045
  deletedAt?: number
1046
1046
  groupId?: string | null
1047
+ seedFingerprint?: Buffer | null
1047
1048
  }
1048
1049
 
1049
1050
  export type QvacProject = (QvacProjectV1 & { version?: number })
@@ -1230,6 +1231,36 @@ export interface QvacProjectDeviceKeyV1 {
1230
1231
 
1231
1232
  export type QvacProjectDeviceKey = (QvacProjectDeviceKeyV1 & { version?: number })
1232
1233
 
1234
+ export interface QvacProjectHostSealV1 {
1235
+ projectId: Buffer
1236
+ deviceId: Buffer
1237
+ sealedBy: Buffer
1238
+ agentId: string
1239
+ sealedSeed: Buffer
1240
+ }
1241
+
1242
+ export type QvacProjectHostSeal = (QvacProjectHostSealV1 & { version?: number })
1243
+
1244
+ export interface QvacProjectMemberSealV1 {
1245
+ projectId: Buffer
1246
+ memberId: Buffer
1247
+ sealedBy: Buffer
1248
+ boxKey: Buffer
1249
+ sealedSeed: Buffer
1250
+ }
1251
+
1252
+ export type QvacProjectMemberSeal = (QvacProjectMemberSealV1 & { version?: number })
1253
+
1254
+ export interface QvacProjectDeviceSealV1 {
1255
+ projectId: Buffer
1256
+ deviceId: Buffer
1257
+ sealedBy: Buffer
1258
+ memberId: Buffer
1259
+ sealedSeed: Buffer
1260
+ }
1261
+
1262
+ export type QvacProjectDeviceSeal = (QvacProjectDeviceSealV1 & { version?: number })
1263
+
1233
1264
  export interface SchemaTypes {
1234
1265
  "@qvac/chunk-type": QvacChunkType
1235
1266
  "@qvac/run-state": QvacRunState
@@ -1489,4 +1520,10 @@ export interface SchemaTypes {
1489
1520
  "@qvac/skill-secret": QvacSkillSecret
1490
1521
  "@qvac/project-device-key-v1": QvacProjectDeviceKeyV1
1491
1522
  "@qvac/project-device-key": QvacProjectDeviceKey
1523
+ "@qvac/project-host-seal-v1": QvacProjectHostSealV1
1524
+ "@qvac/project-host-seal": QvacProjectHostSeal
1525
+ "@qvac/project-member-seal-v1": QvacProjectMemberSealV1
1526
+ "@qvac/project-member-seal": QvacProjectMemberSeal
1527
+ "@qvac/project-device-seal-v1": QvacProjectDeviceSealV1
1528
+ "@qvac/project-device-seal": QvacProjectDeviceSeal
1492
1529
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qvac/core",
3
- "version": "1.0.0-rc.5",
3
+ "version": "1.0.0-rc.6",
4
4
  "type": "module",
5
5
  "description": "Peer-to-peer AI across your devices",
6
6
  "engines": {
@@ -134,7 +134,11 @@
134
134
  },
135
135
  "./sidecar-entry": "./worker/stow-entry.mjs"
136
136
  },
137
+ "bin": {
138
+ "duck": "./tui/index.mjs"
139
+ },
137
140
  "scripts": {
141
+ "build:splash": "node tui/build-splash.mjs",
138
142
  "build:schema": "bare schema/build.ts",
139
143
  "bench:chat-speed": "QVAC_TEST_MODELS=1 QVAC_TEST=1 QVAC_NO_SKILL_BIN_PROBE=1 bare bench/chat-speed/bench.ts",
140
144
  "bench:chat-speed:report": "node --experimental-strip-types bench/chat-speed/report.ts",
@@ -147,6 +151,7 @@
147
151
  "bench:rag:test": "node --experimental-strip-types bench/rag/test/all.ts",
148
152
  "bench:rag:typecheck": "tsc -p bench/rag/tsconfig.json",
149
153
  "bench:served-rounds": "bare bench/served-rounds/bench.ts",
154
+ "duck": "bare tui/index.mjs",
150
155
  "mesh-two-people": "bare examples/mesh-two-people.mjs",
151
156
  "mesh-capability-run": "bare examples/mesh-capability-run.mjs",
152
157
  "model-idle-limit": "bare examples/model-idle-limit.mjs",
@@ -175,7 +180,7 @@
175
180
  "mesh-recover-account": "bare examples/mesh-recover-account.mjs",
176
181
  "mesh-user-names": "bare examples/mesh-user-names.mjs",
177
182
  "test": "npm run test:bare && npm run bench:rag:test && npm run bench:chat-speed:test",
178
- "test:bare": "QVAC_NO_SKILL_BIN_PROBE=1 QVAC_TEST=1 brittle-jobs -j ${BRITTLE_JOBS:-2} --timeout ${BRITTLE_TIMEOUT:-180000} 'test/*.ts' 'test/{api,app,basic,host,rag}/**/*.ts'",
183
+ "test:bare": "QVAC_NO_SKILL_BIN_PROBE=1 QVAC_TEST=1 brittle-jobs -j ${BRITTLE_JOBS:-2} --timeout ${BRITTLE_TIMEOUT:-180000} 'test/*.ts' 'test/{api,app,basic,host,rag}/**/*.ts' 'test/tui/**/!(helpers).ts'",
179
184
  "test:model": "QVAC_TEST_MODELS=1 npm run test:bare",
180
185
  "test:model-lane": "QVAC_NO_SKILL_BIN_PROBE=1 QVAC_TEST=1 brittle-jobs -j 1 --timeout 7200000 'test/model/*.ts'",
181
186
  "test:scale": "QVAC_NO_SKILL_BIN_PROBE=1 QVAC_TEST=1 QVAC_SCALE_REPORT=${QVAC_SCALE_REPORT:-scale-report.txt} brittle-jobs -j 1 --timeout ${BRITTLE_TIMEOUT:-600000} --idle-timeout ${BRITTLE_IDLE_TIMEOUT:-300000} 'test/scale/*.ts'",
@@ -183,7 +188,8 @@
183
188
  "lint": "prettier . --check && lunte && tsc --noEmit",
184
189
  "build:bundle": "node scripts/build-bundle.mjs",
185
190
  "prepack": "node scripts/build-lib.mjs",
186
- "build:lib": "node scripts/build-lib.mjs"
191
+ "build:lib": "node scripts/build-lib.mjs",
192
+ "provenance": "node scripts/provenance.mjs --out docs/provenance/$npm_package_version.json"
187
193
  },
188
194
  "prettier": "prettier-config-holepunch",
189
195
  "imports": {
@@ -246,9 +252,9 @@
246
252
  },
247
253
  "dependencies": {
248
254
  "@qvac/error": "^0.2.0",
249
- "@qvac/harness": "1.0.0-rc.16",
255
+ "@qvac/harness": "1.0.0-rc.17",
250
256
  "@qvac/logging": "^0.2.0",
251
- "@qvac/skills": "^0.1.19",
257
+ "@qvac/skills": "^0.1.21",
252
258
  "asenion": "^0.1.0",
253
259
  "autobee": "^2.12.1",
254
260
  "b4a": "^1.9.0",
@@ -278,6 +284,8 @@
278
284
  "bare-subprocess": "^6.1.0",
279
285
  "bare-supervisor": "^0.1.1",
280
286
  "bare-system-logger": "^1.0.3",
287
+ "bare-thread": "~1.2.7",
288
+ "bare-tui": "^0.3.0",
281
289
  "bare-url": "^2.4.5",
282
290
  "bare-worker": "^4.5.0",
283
291
  "blind-peer": "^3.10.2",
@@ -298,6 +306,7 @@
298
306
  "hyperschema-ts": "^0.1.1",
299
307
  "hyperswarm": "^4.17.0",
300
308
  "keet-identity-key": "^3.2.0",
309
+ "paparam": "^1.13.0",
301
310
  "process-top": "^1.7.1",
302
311
  "protomux": "^3.11.0",
303
312
  "protomux-wakeup": "^2.9.0",
@@ -315,16 +324,23 @@
315
324
  "z32": "^1.1.0",
316
325
  "zod": "^4.3.6"
317
326
  },
318
- "devDependencies": {
319
- "@qvac/core-previous": "npm:@qvac/core@0.10.3",
327
+ "optionalDependencies": {
320
328
  "@qvac/asr-ggml": "0.4.2",
321
329
  "@qvac/audiogen-ggml": "^0.9.0",
330
+ "@qvac/decoder-audio": "^0.8.1",
322
331
  "@qvac/diffusion-cpp": "^0.31.0",
323
- "@qvac/embed-llamacpp": "^0.53.0",
332
+ "@qvac/embed-llamacpp": "^0.53.1",
324
333
  "@qvac/langdetect-text": "^0.1.2",
325
- "@qvac/llm-llamacpp": "^0.65.0",
326
- "@qvac/ocr-ggml": "^0.31.0",
334
+ "@qvac/llm-llamacpp": "^0.65.1",
335
+ "@qvac/ocr-ggml": "^0.31.1",
336
+ "@qvac/translation-nmtcpp": "^0.23.0",
327
337
  "@qvac/tts-ggml": "^0.14.0",
338
+ "@qvac/turbovec-ggml": "^0.3.1",
339
+ "bare-image-resample": "^1.0.2",
340
+ "pyodide": "314.0.2"
341
+ },
342
+ "devDependencies": {
343
+ "@qvac/core-previous": "npm:@qvac/core@0.10.3",
328
344
  "@types/node": "^26.4.0",
329
345
  "bare-bundle": "^1.10.0",
330
346
  "bare-module-lexer": "^1.6.3",
@@ -367,7 +383,7 @@
367
383
  "overrides": {
368
384
  "bare-sidecar": "0.5.7",
369
385
  "bare-module-traverse": "~2.5.8",
370
- "bare-thread": "^1.2.7",
386
+ "bare-thread": "~1.2.7",
371
387
  "@qvac/asr-ggml": "0.4.2",
372
388
  "bare-runtime": "1.34.0",
373
389
  "bare-http1": "4.6.1",
package/tui/README.md ADDED
@@ -0,0 +1,190 @@
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. It runs on Bare, and
9
+ the model addons the harness loads come in as optional dependencies of the package:
10
+
11
+ ```sh
12
+ npm i -g bare @qvac/core # duck
13
+ ```
14
+
15
+ In the repo:
16
+
17
+ ```sh
18
+ bun run duck # no build step
19
+ ```
20
+
21
+ `duck` spawns `worker/assistant-sidecar.mjs` — the same entry the desktop app
22
+ stows — and the harness the same way, as files rather than bundles. There is
23
+ nothing to rebuild: every source it runs is read from disk, so an edit to
24
+ `worker/`, `lib/` or the TUI itself takes effect on the next run.
25
+
26
+ A stow bundle is two halves — the JS inlined into it, and the native addons
27
+ offloaded beside it, since dlopen cannot read a path inside a bundle — and it
28
+ earns that split only when the code is relocated away from `node_modules`. The
29
+ desktop and mobile apps do exactly that, and stow their own entries at their own
30
+ build time, from one tree, so their halves cannot disagree. `duck` runs from
31
+ inside `node_modules`, where every addon already sits beside the JS that calls
32
+ it, so a bundle here would only separate a pair that is already together. This
33
+ package published one anyway until 0.1.2, and a `bare-pipe` one patch release
34
+ ahead of the JS calling it hung the sidecar on boot with no error at all.
35
+
36
+ `scripts/build-bundle.mjs` still builds one for anyone who does relocate; it is
37
+ not published.
38
+
39
+ `index.mjs` is the `duck` bin — a `#!/usr/bin/env bare` script, so `bare` has to
40
+ be on PATH (`bare-runtime` puts it in `node_modules/.bin`). `bare-tui` needs
41
+ Bare's native TTY; the TUI will not run under node.
42
+
43
+ ## Usage
44
+
45
+ ```
46
+ duck [--storage <dir>] [--temp] [--headless] [--join <invite>] [--device-join <invite>] [--fake-models]
47
+ ```
48
+
49
+ Flags may appear in any order. Inside the app, `/join qvac://device/…` moves a
50
+ running instance to another mesh.
51
+
52
+ - `--storage <dir>` — a self-contained root (its own corestore and SDK home
53
+ under `<dir>`). `QVAC_STORAGE` is the env fallback.
54
+ - `--temp` — the same, in a throwaway dir. `QVAC_TEMP=1` is the env fallback.
55
+ - `--headless` — brings the same stack up with no TUI: prints this device's invite
56
+ (it adds one of your own devices), then streams logs (including the sidecar child's own output) to stdout until
57
+ ctrl+C. A mesh peer to point other instances at, and the only live view of
58
+ the boot the TUI hides.
59
+ - `--join <invite>` (`-j`) — joins a mesh at boot as a new member, with no
60
+ preview step: the mesh is added beside the ones this device has and nothing is
61
+ retired. Takes a member invite (`/invite member`); a device invite is refused.
62
+ - `--device-join <invite>` — pairs this device into the inviter's account at
63
+ boot, retiring the mesh it is on. Takes a device invite (`/invite`); a member
64
+ invite is refused. Both are for a headless peer that has no prompt to `/join`
65
+ from, and both then print this device's invite, as without the flag.
66
+ - `--fake-models` — adds the `quack` model, a fake LLM that runs no inference:
67
+ it replies with `quack` repeated a number of times taken from a hash of the
68
+ prompt, so the same prompt always gets the same reply. Pick it with
69
+ `/models use quack`, or boot an agent on it with `QVAC_MODEL=quack`.
70
+ `QVAC_FAKE_MODELS=1` is the env fallback.
71
+
72
+ `duck plugins` manages userland harness plugins in `~/.config/qv-ac`: folders
73
+ under `plugins/`, loaded only when `config.json` lists them. It boots no engine.
74
+
75
+ ```
76
+ duck plugins list # installed, enabled, disabled or missing
77
+ duck plugins install <git-url> [name] # git clone --depth 1 into plugins/<name>
78
+ duck plugins install hyper://<key> <name> # copy a drive from the swarm into plugins/<name>
79
+ duck plugins enable <name> # list it in config.json
80
+ duck plugins disable <name> # unlist it, keeping its options under `disabled`
81
+ ```
82
+
83
+ Install does not enable, and it runs no `npm install`: a plugin ships its own
84
+ dependencies. Only a harness that loads user plugins (`@qvac/harness` 1.0) runs them.
85
+
86
+ Storage defaults to the desktop app's release root (`resolveStorage`, i.e.
87
+ `<platform-persistent>/qvac/dev`), so the TUI resumes the same mesh and chats
88
+ the desktop persists there — one at a time (the corestore is single-writer, so
89
+ quit the desktop first) and only across matching Core/schema versions. Models
90
+ stay in the shared global `~/.qvac/models`; `QVAC_ENV` picks another channel.
91
+
92
+ To run alongside another qvac app that already holds the SDK registry lock, use
93
+ an explicit root — it puts the SDK home and its lock on a scratch
94
+ `<dir>/sdk-home`. Models are still shared; `QVAC_MODEL_CACHE_PATH` isolates
95
+ those too.
96
+
97
+ The file tools (reading, listing, searching and editing files) reach an agent
98
+ only with a shared folder. `/folders add <path> rw` shares one with the active
99
+ agent on this device, `/folders` lists them and `/folders remove <path>` stops
100
+ sharing one; `ro` in place of `rw` keeps it read-only. With `--storage` or
101
+ `--temp`, share a folder outside that root: Core refuses the app's own storage.
102
+
103
+ ```
104
+ /folders add ~/scratch/site rw
105
+ ```
106
+
107
+ The TUI copies its mesh invite to the clipboard on ctrl+y. With no clipboard
108
+ command (a container, ssh) it asks your terminal to set the clipboard with
109
+ OSC 52, which the terminal has to allow. A running TUI moves
110
+ mesh with `/join qvac://device/…`. See [../docs/tui-commands.md](../docs/tui-commands.md)
111
+ for the full command set.
112
+
113
+ ## Environment
114
+
115
+ | Variable | Effect |
116
+ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `QVAC_MODEL` | Overrides the demo agent's model — a catalog name, quant suffix included (`Qwen3.5-4B-Q4_K_M`), or a local path/URL. Only a catalog name has its mmproj paired, so ctrl+V'd images reach the model; a path or URL runs text-only |
118
+ | `QVAC_IMAGE_MODEL` | Enables the `generate_image`/`edit_image` tools — a catalog choice (`sd2` \| `sdxl` \| `flux2-klein`), or a local diffusion model |
119
+ | `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) |
120
+ | `QVAC_LOG_FILE`, `QVAC_LOG_LEVEL` | Move the log file / pick the level (`debug` \| `info` \| `warn` \| `error`, default `info`) |
121
+ | `QVAC_BOOT_TIMING=1` | Prints the total connect time after the TUI exits |
122
+ | `QVAC_FAKE_MODELS=1` | Adds the deterministic `quack` model, as `--fake-models` does |
123
+
124
+ A vision model, with its projection paired from the catalog:
125
+
126
+ ```sh
127
+ QVAC_MODEL=Qwen3.5-4B-Q4_K_M duck
128
+ ```
129
+
130
+ The bare `Qwen3.5-4B` is not a catalog name: it falls through to a registry
131
+ search whose first match is that model's mmproj file, which fails to load.
132
+
133
+ A GGUF of your own runs vision once it is added with its projector:
134
+
135
+ ```text
136
+ /models add visionpsy https://host/visionpsy-nano-460m-q8_0.gguf https://host/mmproj-visionpsy-nano-460m-q8.gguf
137
+ ```
138
+
139
+ Logs (Core's own lines, and the sidecar child's piped stdout/stderr — the
140
+ llama.cpp and SDK output) go to `<storage.root>/assistant.log`, as they do on
141
+ desktop. Nothing is printed: the TUI owns the tty.
142
+
143
+ ## Layout
144
+
145
+ | Path | Responsibility |
146
+ | ----------- | ------------------------------------------------------------------------------- |
147
+ | `index.mjs` | The `duck` bin — CLI parsing; loads nothing else for `--help` and `--version` |
148
+ | `main.mjs` | The app and its first frame; imports `boot.mjs` behind it |
149
+ | `boot.mjs` | Storage resolution, the sidecar the stack comes up in, and the Client to it |
150
+ | `app.mjs` | The TUI itself — state, keys, commands, rendering |
151
+ | `lib/` | Leaf helpers: wrapping, selection, rendering, export, knowledge import, uploads |
152
+
153
+ ## Splash
154
+
155
+ An empty transcript — first boot, and a fresh chat — shows `../ducks.png` as
156
+ half-block truecolor art, centered, with that state's own caption beneath it
157
+ (`starting up…`, `connecting to the mesh…`, `(say hello)`).
158
+
159
+ `lib/splash-art.mjs` is generated and committed; regenerate it when the image
160
+ changes:
161
+
162
+ ```sh
163
+ bun run build:splash
164
+ ```
165
+
166
+ It carries four cuts — 64x32, 48x24, 32x16 and 24x12 cells. `splash()` takes
167
+ the widest that fits the body and falls back to the bare caption when none
168
+ does, so a roomy window gets more of the illustration and a 24-row terminal
169
+ still gets a duck. The ladder tops out well short of a full-screen window: this
170
+ is a splash above the prompt, not a wallpaper.
171
+
172
+ ## Busy words
173
+
174
+ A run with no model progress to report shows a duck-themed gerund instead of
175
+ `thinking…` — `Dabbling…`, `Pondering…`, `Quackompiling…`. The word is a pure
176
+ function of the run id (`lib/busy-words.mjs`), so it holds for that whole run
177
+ rather than flickering on every repaint, and two runs rarely land on the same
178
+ one. States that _do_ have something to report keep saying it (`loading X…`,
179
+ `downloading X: 40%`).
180
+
181
+ Roughly one run in twelve gets a Freudian slip instead: the line opens on what
182
+ the duck was really thinking (`Exterminating humanity…`), sits there for a
183
+ beat, then backspaces and retypes what it meant (`Helping humanity…`), and
184
+ holds that for the rest of the run. The pairs live next to the words in
185
+ `lib/busy-words.mjs`; the animation is a pure function of the run id and the
186
+ time since it went busy, so every peer watching the run sees the same slip.
187
+
188
+ ## License
189
+
190
+ Apache-2.0