@qvac/core 1.0.0-rc.3 → 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 (135) hide show
  1. package/CHANGELOG.md +147 -36
  2. package/README.md +55 -4
  3. package/dist-lib/index.d.ts +2 -1
  4. package/dist-lib/lib/api/agents.d.ts +2 -1
  5. package/dist-lib/lib/api/agents.js +5 -1
  6. package/dist-lib/lib/api/app-config.d.ts +3 -0
  7. package/dist-lib/lib/api/app-config.js +20 -0
  8. package/dist-lib/lib/api/approval-rules.d.ts +1 -1
  9. package/dist-lib/lib/api/approval-rules.js +5 -1
  10. package/dist-lib/lib/api/config.d.ts +6 -2
  11. package/dist-lib/lib/api/config.js +9 -5
  12. package/dist-lib/lib/api/device-routes.d.ts +1 -1
  13. package/dist-lib/lib/api/device-routes.js +3 -1
  14. package/dist-lib/lib/api/index.d.ts +12 -2
  15. package/dist-lib/lib/api/index.js +8 -2
  16. package/dist-lib/lib/api/projects.js +3 -4
  17. package/dist-lib/lib/api/rag.js +5 -5
  18. package/dist-lib/lib/api/served.d.ts +2 -2
  19. package/dist-lib/lib/api/served.js +24 -1
  20. package/dist-lib/lib/assistant/harness.d.ts +3 -0
  21. package/dist-lib/lib/assistant/history.js +14 -2
  22. package/dist-lib/lib/assistant/message.d.ts +1 -0
  23. package/dist-lib/lib/assistant/model-round.d.ts +3 -0
  24. package/dist-lib/lib/assistant/model-round.js +18 -4
  25. package/dist-lib/lib/assistant/round-host.d.ts +2 -0
  26. package/dist-lib/lib/assistant/round-host.js +8 -0
  27. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  28. package/dist-lib/lib/assistant-tree.js +4 -2
  29. package/dist-lib/lib/assistant.d.ts +12 -1
  30. package/dist-lib/lib/assistant.js +131 -15
  31. package/dist-lib/lib/client.js +4 -1
  32. package/dist-lib/lib/core/agent-copies.js +9 -2
  33. package/dist-lib/lib/core/agent-hosting.js +9 -4
  34. package/dist-lib/lib/core/agent.js +3 -1
  35. package/dist-lib/lib/core/approval-rules.d.ts +5 -1
  36. package/dist-lib/lib/core/approval-rules.js +16 -1
  37. package/dist-lib/lib/core/chat-copy.d.ts +1 -0
  38. package/dist-lib/lib/core/chat-copy.js +13 -2
  39. package/dist-lib/lib/core/chat.d.ts +0 -1
  40. package/dist-lib/lib/core/chat.js +0 -3
  41. package/dist-lib/lib/core/chunk.js +4 -3
  42. package/dist-lib/lib/core/collections.d.ts +7 -7
  43. package/dist-lib/lib/core/collections.js +7 -7
  44. package/dist-lib/lib/core/config-value.d.ts +1 -0
  45. package/dist-lib/lib/core/config-value.js +1 -0
  46. package/dist-lib/lib/core/contract/project-device-keys.d.ts +4 -2
  47. package/dist-lib/lib/core/contract/project-device-keys.js +12 -12
  48. package/dist-lib/lib/core/contract/project-host-keys.d.ts +5 -3
  49. package/dist-lib/lib/core/contract/project-host-keys.js +22 -11
  50. package/dist-lib/lib/core/contract/projects.d.ts +4 -2
  51. package/dist-lib/lib/core/contract/projects.js +29 -17
  52. package/dist-lib/lib/core/contract/workspace.js +2 -2
  53. package/dist-lib/lib/core/deleted-agent-runs.d.ts +8 -0
  54. package/dist-lib/lib/core/deleted-agent-runs.js +57 -0
  55. package/dist-lib/lib/core/files/index.d.ts +1 -1
  56. package/dist-lib/lib/core/files/index.js +4 -2
  57. package/dist-lib/lib/core/helpers/index.d.ts +1 -1
  58. package/dist-lib/lib/core/helpers/index.js +2 -2
  59. package/dist-lib/lib/core/local/index.d.ts +6 -0
  60. package/dist-lib/lib/core/local/index.js +14 -0
  61. package/dist-lib/lib/core/mesh.d.ts +2 -1
  62. package/dist-lib/lib/core/mesh.js +7 -5
  63. package/dist-lib/lib/core/project-keys.d.ts +5 -2
  64. package/dist-lib/lib/core/project-keys.js +15 -6
  65. package/dist-lib/lib/core/skill-secrets.d.ts +3 -2
  66. package/dist-lib/lib/core/skill-secrets.js +4 -1
  67. package/dist-lib/lib/core/sync/index.js +18 -6
  68. package/dist-lib/lib/core/vault-managed-skills.d.ts +18 -0
  69. package/dist-lib/lib/core/vault-managed-skills.js +105 -0
  70. package/dist-lib/lib/core.d.ts +10 -1
  71. package/dist-lib/lib/core.js +165 -31
  72. package/dist-lib/lib/errors.d.ts +8 -0
  73. package/dist-lib/lib/errors.js +8 -0
  74. package/dist-lib/lib/kv-cache-ledger.d.ts +22 -0
  75. package/dist-lib/lib/kv-cache-ledger.js +72 -0
  76. package/dist-lib/lib/kv-cache-retention.d.ts +1 -0
  77. package/dist-lib/lib/kv-cache-retention.js +5 -2
  78. package/dist-lib/lib/mesh-scoped-engine.js +1 -0
  79. package/dist-lib/lib/model-memory-cap.d.ts +3 -0
  80. package/dist-lib/lib/model-memory-cap.js +15 -6
  81. package/dist-lib/lib/run-replay.d.ts +3 -2
  82. package/dist-lib/lib/run-replay.js +16 -5
  83. package/dist-lib/lib/run-transcript.js +1 -1
  84. package/dist-lib/schema/config.d.ts +1 -1
  85. package/dist-lib/schema/config.js +1 -1
  86. package/dist-lib/schema/engine.js +87 -2
  87. package/dist-lib/schema/qvac.js +66 -3
  88. package/dist-lib/spec/bind.js +15 -0
  89. package/dist-lib/spec/calls.js +5 -0
  90. package/dist-lib/spec/capabilities.d.ts +10 -0
  91. package/dist-lib/spec/config/hyperconf/index.js +1 -1
  92. package/dist-lib/spec/hrpc/hrpc.json +65 -0
  93. package/dist-lib/spec/hrpc/index.js +63 -3
  94. package/dist-lib/spec/hrpc/messages.js +1302 -993
  95. package/dist-lib/spec/hyperschema/index.js +1302 -993
  96. package/dist-lib/spec/hyperschema/schema.json +227 -0
  97. package/dist-lib/spec/hyperschema/types.d.ts +45 -0
  98. package/dist-lib/spec/mesh/hyperdb/db.json +110 -0
  99. package/dist-lib/spec/mesh/hyperdb/index.js +498 -2
  100. package/dist-lib/spec/mesh/hyperdb/messages.js +1385 -892
  101. package/dist-lib/spec/mesh/hyperdispatch/messages.js +561 -301
  102. package/dist-lib/spec/mesh/hyperschema/index.js +561 -301
  103. package/dist-lib/spec/mesh/hyperschema/schema.json +343 -178
  104. package/dist-lib/spec/mesh/hyperschema/types.d.ts +40 -1
  105. package/package.json +34 -18
  106. package/tui/README.md +190 -0
  107. package/tui/app.mjs +8247 -0
  108. package/tui/boot.mjs +159 -0
  109. package/tui/index.mjs +89 -0
  110. package/tui/lib/boot-timing.mjs +41 -0
  111. package/tui/lib/busy-words.mjs +116 -0
  112. package/tui/lib/connect-sheet.mjs +350 -0
  113. package/tui/lib/device-target.mjs +64 -0
  114. package/tui/lib/export.mjs +194 -0
  115. package/tui/lib/folders-command.mjs +84 -0
  116. package/tui/lib/fork-command.mjs +43 -0
  117. package/tui/lib/knowledge-command.mjs +190 -0
  118. package/tui/lib/knowledge-import.mjs +153 -0
  119. package/tui/lib/local-path.mjs +21 -0
  120. package/tui/lib/move-command.mjs +17 -0
  121. package/tui/lib/render.mjs +225 -0
  122. package/tui/lib/save-file.mjs +88 -0
  123. package/tui/lib/select.mjs +81 -0
  124. package/tui/lib/selection.mjs +18 -0
  125. package/tui/lib/setup.mjs +135 -0
  126. package/tui/lib/sidebar.mjs +63 -0
  127. package/tui/lib/skill-connect.mjs +145 -0
  128. package/tui/lib/splash-art.mjs +107 -0
  129. package/tui/lib/splash.mjs +18 -0
  130. package/tui/lib/upload-frames.mjs +9 -0
  131. package/tui/lib/usage.mjs +59 -0
  132. package/tui/lib/wrap.mjs +143 -0
  133. package/tui/main.mjs +279 -0
  134. package/tui/plugins.mjs +158 -0
  135. package/worker/assistant-sidecar.mjs +1 -0
package/CHANGELOG.md CHANGED
@@ -15,6 +15,11 @@ release.
15
15
 
16
16
  ### Added
17
17
 
18
+ - A vision model sees an image a tool attaches during a run, such as a PNG `http_request` downloads
19
+ from Google Drive. The assistant gives the harness the image from its own image cache, as it does
20
+ a user's image, and the harness shows it on the turn that closes the tool round. Later runs show
21
+ it again on the same turn. Video stays an attachment for now. Needs a harness with `showImage`.
22
+
18
23
  - A completed run that primed the chat cache after Core deleted it says so on its
19
24
  `run-status.metrics`: `cacheRebuild` carries Core's deletion reason and the prompt tokens of the
20
25
  run's first round on the key, as its `metrics.rounds` counts them, null when that round has no
@@ -66,27 +71,28 @@ release.
66
71
  passes it to `Core`. Unset keeps today's behaviour; `false` starts a host
67
72
  without fetching the default models. A sidecar that fails to start also writes
68
73
  the reason to stderr, since the host may not be listening yet.
69
-
70
- - A chat's KV cache is deleted once the chat has been idle for the retention, so a device no
71
- longer keeps the cache of every chat it ever ran. The chat itself is untouched; its next message
72
- primes from history. An app sets its default with `kvCacheRetentionMs` on `assistantChild` (14
73
- days without it, `0` for Never), and a device overrides it with `kvCache.retentionDays`.
74
-
75
- ```js
76
- import { assistantChild } from '@qvac/core'
77
- import { KV_CACHE_RETENTION_KEY } from '@qvac/core/constants'
78
-
79
- assistantChild({ harness, kvCacheRetentionMs: 30 * 24 * 60 * 60_000 })
80
- await engine.configSet({ key: KV_CACHE_RETENTION_KEY, value: 7 })
81
- ```
74
+ - `duck plugins list|install|enable|disable` manages the userland harness
75
+ plugins in `~/.config/qv-ac` without booting an engine. Install clones a git
76
+ URL or copies a `hyper://` drive, and does not enable what it installs.
77
+ - `npm i -g bare @qvac/core` runs `duck`: the model addons the harness's stock entry loads are
78
+ optional dependencies of the package, so an install brings them, and `bare-thread` is pinned to
79
+ `~1.2.7` in `dependencies`, since 1.4 fails to load the stowed harness worker.
82
80
 
83
81
  ### Changed
84
82
 
83
+ - A streaming reply lands in its chat about once a second instead of every 250 ms: `RunTranscript`
84
+ flushes buffered text on a 1 s tick (and still at 8,192 chars, on a type or round change and at the
85
+ end). A client watching the chat gets a quarter of the frames, so it should pace its own text
86
+ animation by how often text arrives rather than assume a fixed cadence. On a Pixel 8 this cut
87
+ app CPU per generated token by about 30% and skin heating per token by 20–40%, with decode speed
88
+ unchanged.
89
+ ([decision](docs/decisions/2026-11-05-a-streaming-reply-lands-once-a-second.md))
90
+
85
91
  - The KV cache retention sweep runs every 12 hours instead of every hour, besides when a mesh opens
86
92
  and when `kvCache.retentionDays` changes, so a cache can outlive its retention by up to 12 hours
87
93
  on a host that stays up. ([config.md](docs/api/config.md#kv-cache-retention))
88
94
 
89
- - Core depends on `@qvac/harness` 1.0.0-rc.12 from npm instead of a git commit, so a consumer installs
95
+ - Core depends on `@qvac/harness` 1.0.0-rc.17 from npm instead of a git commit, so a consumer installs
90
96
  the published harness with its named entries.
91
97
 
92
98
  - Wipe a store written by 1.0.0-rc.0 to rc.2 before running this build. The collection, route and
@@ -97,31 +103,67 @@ release.
97
103
  its rc-numbered ops, so a device that rejoins it, by a recovery from the phrase too, misreads
98
104
  them again. Start a new account on this build instead.
99
105
 
100
- - The baked version floor is `>=0.21.0`: one build per mesh, since v0.21 changes
101
- what apply admits. Each mesh now holds a rules row, `@qvac/mesh-rules`, first
102
- in a new mesh's genesis and appended once when this build first holds an
103
- existing mesh writable, and apply holds new rules to ops after it only. A
104
- 0.7.x replica that applies the row halts into its update prompt.
106
+ - The baked version floor is `>=0.22.0`: one build per mesh, since this release
107
+ changes what apply admits and app 0.22 is the first to ship it. Each mesh now
108
+ holds a rules row, `@qvac/mesh-rules`, first in a new mesh's genesis and
109
+ appended once when this build first holds an existing mesh writable, and apply
110
+ holds new rules to ops after it only. A 0.7.x or 0.11.x replica that applies
111
+ the row halts into its update prompt.
105
112
 
106
- **Operator step:** publish `>=0.21.0` with `qvac-app → scripts/ota-config.mjs`
107
- on each lane (dev, staging, prod) only once app 0.21 is live on that lane, and
113
+ **Operator step:** publish `>=0.22.0` with `qvac-app → scripts/ota-config.mjs`
114
+ on each lane (dev, staging, prod) only once app 0.22 is live on that lane, and
108
115
  never before: a floor above the installed release withholds every device on
109
- the lane. Until it is published, an old replica that fast-forwards past the row
110
- applies later ops under the old rules.
116
+ the lane. Not `>=0.21.0`, which admits app 0.21 and its core 0.11.1, from
117
+ before the row. Until it is published, an old replica that fast-forwards past
118
+ the row applies later ops under the old rules.
111
119
 
112
120
  - A rules row raised above the rules this build knows halts apply into its
113
121
  update prompt with the code `MESH_RULES_FROM_A_NEWER_BUILD`, instead of being
114
122
  applied.
115
123
 
116
- - A `mesh write` or `mesh drain` stall now keeps reporting while it lasts. Each `… still pending`
124
+ ### Removed
125
+
126
+ - `duck`'s `/agent borrow` and `/mesh new compute`, now that Core 1.0 retires
127
+ model loans and compute meshes.
128
+
129
+ ### Fixed
130
+
131
+ - A run that restarts mid-reply no longer has its host write the abandoned round's answer a second
132
+ time beside the new attempt's: the run cancels the model rounds its earlier attempt left open
133
+ before it starts again.
134
+ - A resume whose announce reached no DHT node retries that topic within
135
+ seconds, instead of leaving the device unfindable for ten minutes.
136
+ - A chat cache whose workspace this device no longer sees is deleted: left while the device was
137
+ closed, before it heard of the leave, or a member's chats it served. The assistant records which
138
+ chats it built a cache for and, at boot and whenever a mesh leaves the list, deletes those no open
139
+ mesh lists. A host keeps that record beside the run replays, through the new `kvCacheChatsDir`
140
+ option, so a data reset takes both; retention Never turns the sweep off too.
141
+
142
+ ```js
143
+ assistantTree({ runReplayDir: `${root}/run-replay`, kvCacheChatsDir: `${root}/kv-cache-chats` })
144
+ ```
145
+
146
+ - A device that hosts another member's agent sweeps its chat caches too: KV cache retention and the
147
+ orphaned cache sweep read a hosted mesh through `listChats`, which the assistant's connection now
148
+ answers there with the chats it serves, instead of failing the whole sweep. A host restart keeps
149
+ the caches it serves until hosting resumes, instead of deleting them at boot.
150
+ - Upgrading from app 0.21 no longer reruns a send that was still unanswered in a private chat. The
151
+ private chats copied into your own workspace now end an open run as failed, as the chats copied
152
+ into a project already did, instead of leaving a request for the assistant to take. An approval
153
+ that run was holding is denied in the copy in both places, so none stays pending on a failed run.
154
+
155
+ ## [0.11.4] - 2026-10-30
156
+
157
+ ### Changed
158
+
159
+ - A `mesh write` or `mesh drain` stall now keeps reporting while it lasts (#649). Each `… still pending`
117
160
  line carries `reports` (1, 2, 3 …), and the wait doubles between reports. It also names:
118
161
  - `fastForwarding`: the head a fast-forward is booting onto, with how much of that core this
119
162
  device and its peers hold, or `null`.
120
163
  - `peerLength` and `peerHeld` on every `missing` core: how far the furthest connected peer
121
164
  knows that core, and how much of it that peer holds from block 0.
122
165
  - `writers` on a mesh still joining: each writer it knows, with the same holdings.
123
-
124
- - The logs now name the build and what an open did to an older mesh:
166
+ - The logs now name the build and what an open did to an older mesh (#650):
125
167
  - `core opening` is the first line of a launch. It names the app's `version`, `build` and
126
168
  `channel`, and the mesh `schema` this core applies. A mesh's own `opening` line names the
127
169
  `schema` too.
@@ -131,19 +173,79 @@ release.
131
173
  - `copied chats into chat-chunks` and `recorded the files the mesh already held` give each
132
174
  backfill's count and `ms`.
133
175
 
176
+ ### Fixed
177
+
178
+ - The assistant no longer logs `saveDeviceCapabilities failed` while the account mesh is still
179
+ joining. Core refuses the report with `MESH_STILL_JOINING` until this device is a writer, and the
180
+ assistant already reports again once the account turns writable, so the refusal was never a
181
+ failure. (#648)
182
+
183
+ ## [0.11.3] - 2026-10-28
184
+
185
+ ### Added
186
+
187
+ - The first run to complete stores which pictures of a PDF it sent, as an attachment chunk whose
188
+ `sourceId` is the PDF's attachment id, so later turns and other devices send the same ones. Do
189
+ not render an attachment chunk that carries a `sourceId`. (#640)
190
+
191
+ ### Changed
192
+
193
+ - A PDF's pictures reach a vision model cut to each figure and its caption, named by page and
194
+ figure, instead of as whole pages, and white pages are no longer sent. The PDF's text and its
195
+ pictures now share half the context window, less what the chat already holds, where each took
196
+ half before: a PDF whose whole text fit filled the window and compacted on the next message.
197
+ (#640)
198
+ - `bare-pdfium` is required at `^1.8.0`, for `imageBounds` and `pageBox`; a host that packages the
199
+ addon ships that version. (#640)
200
+
201
+ ## [0.11.2] - 2026-10-28
202
+
203
+ ### Added
204
+
205
+ - A chat's KV cache is deleted once the chat has been idle for the retention, so a device no
206
+ longer keeps the cache of every chat it ever ran. The chat itself is untouched; its next message
207
+ primes from history. An app sets its default with `kvCacheRetentionMs` on `assistantChild` (14
208
+ days without it, `0` for Never), and a device overrides it with `kvCache.retentionDays`. (#589)
209
+
210
+ ```js
211
+ import { assistantChild } from '@qvac/core'
212
+ import { KV_CACHE_RETENTION_KEY } from '@qvac/core/constants'
213
+
214
+ assistantChild({ harness, kvCacheRetentionMs: 30 * 24 * 60 * 60_000 })
215
+ await engine.configSet({ key: KV_CACHE_RETENTION_KEY, value: 7 })
216
+ ```
217
+
218
+ - Every credential a skill declares is pushed to the harness, not only the built-in keys and
219
+ OAuth tokens, so a skill with its own key no longer reads needs-setup for good and needs no core
220
+ release. Where a value may be sent is unchanged, and an overlay skill gets no credential. (#596)
221
+ - A credential with no setup block and no token provider gets a one-field token route named after
222
+ its key, so any setup UI can set it. (#591)
223
+ - `duck` sets a skill up through one sheet, opened by `/skill <name>`. (#592)
224
+
225
+ ### Changed
226
+
227
+ - `toolResult.result` is required on the wire, so a tool result of `false`, `0` or `''` reads
228
+ back as written from `listChunks` and `chunksWatch` instead of `null`. A device on 0.11.0 or
229
+ earlier, and a result one of those releases wrote, still read `null`. (#559)
230
+
231
+ ```js
232
+ // 0.11.1
233
+ { type: 'tool-result', toolResult: { name } }
234
+ // 0.11.2
235
+ { type: 'tool-result', toolResult: { name, result: null } }
236
+ ```
237
+
134
238
  ### Removed
135
239
 
136
- - The `duck` terminal UI and its bin; the terminal app lives in its own repo.
240
+ - `duck`'s `/cred`: every value is set through its skill's sheet. (#593)
137
241
 
138
242
  ### Fixed
139
243
 
140
- - A resume whose announce reached no DHT node retries that topic within
141
- seconds, instead of leaving the device unfindable for ten minutes.
142
244
  - Chat activity no longer diffs across a fast-forward it has not counted yet. It
143
245
  dropped its cached view head only once `fastForwards` moved, which can be
144
246
  after the view has landed on another core, and a diff from the old head read
145
247
  every node of the new view. It now drops the head whenever the view is on
146
- another core, as `chunksDeltaWatch` does.
248
+ another core, as `chunksDeltaWatch` does. (#623)
147
249
  - A device that does not hold a mesh no longer downloads most of it to show chat
148
250
  activity and notifications. Both read a few chunk types per chat, each through
149
251
  its type index and then row by row from `@qvac/chunks`; they now read the
@@ -151,11 +253,17 @@ release.
151
253
  range is whole. A member joining a 170-chat mesh with both open downloaded
152
254
  about 39,000 blocks (155 MB) instead of 258,000 (640 MB), and on a device that
153
255
  holds the mesh their first frames take 2.2 s and 3.7 s instead of 5.8 s and
154
- 9.8 s.
155
- - The assistant no longer logs `saveDeviceCapabilities failed` while the account mesh is still
156
- joining. Core refuses the report with `MESH_STILL_JOINING` until this device is a writer, and the
157
- assistant already reports again once the account turns writable, so the refusal was never a
158
- failure.
256
+ 9.8 s. (#624)
257
+ - `compactChat` folds whole turns, so a chat whose messages were queued no longer keeps answers
258
+ without their questions. (#607)
259
+ - A run whose injected excerpts overflow the model window, with no older turns to fold, is retried
260
+ with half the excerpts instead of failing. (#599)
261
+ - `ragSearch` on a remote agent host waits for an attached file still replicating to it instead of
262
+ answering that the file is still being indexed. (#562)
263
+ - A chat whose first message carries a document is titled from the words the user typed, not the
264
+ document text. (#516)
265
+ - A re-homed agent's skill values are retried until the new host takes them; a host that refused
266
+ before it replicated the re-home left them unset. (#478)
159
267
 
160
268
  ## [0.11.1] - 2026-10-26
161
269
 
@@ -2147,7 +2255,10 @@ Published under the `release-0.1` dist-tag.
2147
2255
  await assistant.ready()
2148
2256
  ```
2149
2257
 
2150
- [Unreleased]: https://github.com/tetherto/qvac-core/compare/v0.11.1...HEAD
2258
+ [Unreleased]: https://github.com/tetherto/qvac-core/compare/v0.11.4...HEAD
2259
+ [0.11.4]: https://github.com/tetherto/qvac-core/compare/v0.11.3...v0.11.4
2260
+ [0.11.3]: https://github.com/tetherto/qvac-core/compare/v0.11.2...v0.11.3
2261
+ [0.11.2]: https://github.com/tetherto/qvac-core/compare/v0.11.1...v0.11.2
2151
2262
  [0.11.1]: https://github.com/tetherto/qvac-core/compare/v0.11.0...v0.11.1
2152
2263
  [0.11.0]: https://github.com/tetherto/qvac-core/compare/v0.10.4...v0.11.0
2153
2264
  [0.10.4]: https://github.com/tetherto/qvac-core/compare/v0.10.3...v0.10.4
package/README.md CHANGED
@@ -21,7 +21,8 @@
21
21
  <a href="#one-shot-tasks">Tasks</a> &middot;
22
22
  <a href="#rendering-the-chunk-stream-any-ui">Chunk stream</a> &middot;
23
23
  <a href="#harness-event-reference">Events</a> &middot;
24
- <a href="#development">Development</a>
24
+ <a href="#development">Development</a> &middot;
25
+ <a href="#the-duck-tui">duck TUI</a>
25
26
  </p>
26
27
 
27
28
  A P2P, multi-device AI workbench core. Three pieces, one duplex stream:
@@ -43,12 +44,22 @@ A P2P, multi-device AI workbench core. Three pieces, one duplex stream:
43
44
 
44
45
  ## Install
45
46
 
47
+ `@qvac/core` is two things: a **library** you embed, and **`duck`**, a terminal
48
+ app that runs the whole stack on top of it.
49
+
46
50
  ```sh
47
- npm i @qvac/core
51
+ npm i @qvac/core # the library
52
+ npm i -g bare @qvac/core # duck, on your PATH, with the Bare it runs on
53
+ ```
54
+
55
+ ```sh
56
+ duck # the TUI
57
+ duck --help
48
58
  ```
49
59
 
50
60
  The library is the three pieces above — start at
51
- [Integrating a harness](#integrating-a-harness). Runnable examples live in
61
+ [Integrating a harness](#integrating-a-harness). `duck` is the fastest way to
62
+ watch them work; it has its own section at [The duck TUI](#the-duck-tui). Runnable examples live in
52
63
  [`examples/`](./examples/README.md); `bun run mesh-two-people` is the shortest
53
64
  one, and shows what a device invite does that a member invite does not.
54
65
 
@@ -655,6 +666,10 @@ MCP-type app registered at app.asana.com), Spotify a client id; Notion needs
655
666
  nothing — its MCP server self-provisions a public client via dynamic
656
667
  registration (RFC 7591) + PKCE.
657
668
 
669
+ In duck, `/skill <name>` opens a skill's setup sheet: what it needs, its fields,
670
+ and the browser sign-in for an OAuth skill. `/skill on <name>` opens it first
671
+ when the skill needs setup, and `/connect <name>` signs in straight away.
672
+
658
673
  ### Notion
659
674
 
660
675
  Notion runs over its official MCP server (`https://mcp.notion.com/mcp`) via
@@ -668,8 +683,11 @@ in a tool result means the token expired — connect Notion again.
668
683
  ```sh
669
684
  npm test # node + bare suites
670
685
  npm run build:schema # regenerate spec/ from schema/ (bare)
686
+ bun run duck # run the TUI (no build step)
671
687
  ```
672
688
 
689
+ The TUI lives in [`tui/`](tui/README.md) and installs as the `duck` command.
690
+
673
691
  Schema changes go in `schema/*.ts` (builders) — `spec/` is generated. The
674
692
  mesh schema (`spec/mesh/*`) is the replicated protocol: every device in a
675
693
  mesh must run the same generated spec. See `MIGRATION.md` for the audited
@@ -679,7 +697,40 @@ feature checklist vs core v1.
679
697
 
680
698
  Core ships no office decoder. Office documents (`.docx`, `.xlsx`, `.pptx`,
681
699
  `.odt`, …) index only when the host passes one through the `extractors.office`
682
- option — the desktop app injects `extractOfficeText` from
700
+ option — the desktop app and `duck` inject `extractOfficeText` from
683
701
  `@qvac/harness/office`. A host without one, such as mobile, fails those files
684
702
  as `extractor unavailable on this device`. Everything else — `.pdf`, `.txt`,
685
703
  `.md`, `.rtf`, `.html`, `.csv`, `.json` and the rest — works from any install.
704
+
705
+ ## The duck TUI
706
+
707
+ `duck` brings the whole stack up — Core, the assistant, your harness — behind a
708
+ terminal UI. It is on your PATH after `npm i -g @qvac/core`, or `bun run duck`
709
+ in this repo. `duck --help` lists the flags, and
710
+ [`docs/tui-commands.md`](docs/tui-commands.md) every slash command.
711
+
712
+ The TUI copies its mesh invite to the clipboard on ctrl+y. On a second machine
713
+ (or a second terminal), start `duck` and join from inside it:
714
+
715
+ ```
716
+ /join qvac://device/…
717
+ ```
718
+
719
+ The preview says who you would join as. A device invite (`/invite`) retires the
720
+ mesh this device is on and pairs it into the inviter's account; a member invite
721
+ (`/invite member`) adds a workspace beside yours. Headless, `duck --join <invite>`
722
+ takes a member invite and `duck --device-join <invite>` a device invite.
723
+
724
+ `--headless` brings the same stack up with no TUI: it prints the invite and then
725
+ streams logs (including the sidecar child's own output, which the TUI drops) to
726
+ stdout until ctrl+C. That is the shape to run as a background mesh peer, and the
727
+ only way to read the engine's logs live — `QVAC_LOG_LEVEL` picks the level:
728
+
729
+ ```sh
730
+ duck --headless
731
+ ```
732
+
733
+ The joiner brings no models — it finds the mesh's agent and asks. The device
734
+ that sends drives the run, the agent's model host serves each model round, and
735
+ both sides watch the same replicated stream: load progress, thinking, tokens,
736
+ tool approvals (either side can answer), and final stats.
@@ -1,6 +1,7 @@
1
1
  export type { AssistantAgent, AssistantAgentList, AssistantConfigValue } from './spec/hyperschema/types.d.ts';
2
2
  export type { Logger } from './lib/logger-type.ts';
3
- export { Core } from './lib/core.ts';
3
+ export { Core, type CoreOptions } from './lib/core.ts';
4
+ export type { VaultManagedSkillField, VaultManagedSkills } from './lib/core/vault-managed-skills.ts';
4
5
  export { Client } from './lib/client.ts';
5
6
  export { AssistantClient } from './lib/assistant-client.ts';
6
7
  export { harnessDeleteModel, harnessListModels, harnessSkillCatalog, harnessTools, QvacAssistant, type Harness, type ListModelsOptions, type ModelInfo, type ModelType, type Skill, type ToolCatalogEntry } from './lib/assistant.ts';
@@ -8,6 +8,7 @@ type AgentCapabilities = Pick<CapabilityHandlers, 'createAgent' | 'listAgents' |
8
8
  export interface CreateAgentsApiOptions {
9
9
  readonly deviceId: Buffer | null;
10
10
  readonly changed?: ((agentId: string) => Promise<void>) | null;
11
+ readonly modelPicked?: ((modelName: string) => Promise<void>) | null;
11
12
  readonly keepCopies?: ((agent: QvacAgent) => Promise<void>) | null;
12
13
  readonly peers?: Pick<MeshStatusSource, 'watch' | 'unwatch' | 'snapshot'> | null;
13
14
  readonly accountChanges?: AccountChanges | null;
@@ -18,5 +19,5 @@ interface AccountChanges {
18
19
  watch(listener: () => void): void;
19
20
  unwatch(listener: () => void): void;
20
21
  }
21
- export declare function createAgentsApi(pool: MeshPool, { deviceId, changed, keepCopies, peers, accountChanges, folders, log }: CreateAgentsApiOptions): AgentCapabilities;
22
+ export declare function createAgentsApi(pool: MeshPool, { deviceId, changed, modelPicked, keepCopies, peers, accountChanges, folders, log }: CreateAgentsApiOptions): AgentCapabilities;
22
23
  export {};
@@ -17,11 +17,12 @@ async function definitions(mesh, rows) {
17
17
  const resolved = await Promise.all(rows.map((row) => runDefinition(mesh, row)));
18
18
  return resolved.filter((row) => row !== null);
19
19
  }
20
- export function createAgentsApi(pool, { deviceId, changed = null, keepCopies = null, peers = null, accountChanges = null, folders, log }) {
20
+ export function createAgentsApi(pool, { deviceId, changed = null, modelPicked = null, keepCopies = null, peers = null, accountChanges = null, folders, log }) {
21
21
  const reachable = () => new Set([
22
22
  ...(peers?.snapshot().peerDeviceIds ?? []),
23
23
  ...(deviceId ? [b4a.toHex(deviceId)] : [])
24
24
  ]);
25
+ const isOwnDefault = (agent) => agent.isDefault === true && !!deviceId && b4a.equals(agent.providerDeviceId, deviceId);
25
26
  const withDerived = async (mesh, agent) => ({
26
27
  ...agent,
27
28
  lenderDeviceId: undefined,
@@ -99,6 +100,9 @@ export function createAgentsApi(pool, { deviceId, changed = null, keepCopies = n
99
100
  const mesh = await requireMesh(pool, meshId);
100
101
  await notPicked(mesh, agentId);
101
102
  const updated = await updateAgent(mesh, agentId, config);
103
+ if (config.modelName && isOwnDefault(updated)) {
104
+ await modelPicked?.(config.modelName);
105
+ }
102
106
  await changed?.(agentId);
103
107
  return withDerived(mesh, updated);
104
108
  },
@@ -4,5 +4,8 @@ import type { openLocalStore } from '../core/local/index.ts';
4
4
  import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
5
5
  type LocalStore = Awaited<ReturnType<typeof openLocalStore>>;
6
6
  export declare function writeAutoDownloadModels(state: LocalStore, enabled: boolean): Promise<AssistantAppConfig>;
7
+ export declare function readLastModelName(state: LocalStore): Promise<string | null>;
8
+ export declare function writeLastModelName(state: LocalStore, name: string): Promise<void>;
9
+ export declare function backfillLastModelName(state: LocalStore, pick: () => Promise<string | null>): Promise<void>;
7
10
  export declare function createAppConfigApi(state: LocalStore, log: LoggerInterface | null): Pick<CapabilityHandlers, 'getConfig' | 'setConfig' | 'setModelPaused' | 'setModelReleased' | 'setAutoDownloadModels' | 'configWatchTyped'>;
8
11
  export {};
@@ -121,6 +121,26 @@ export async function writeAutoDownloadModels(state, enabled) {
121
121
  const row = await state.updateAppConfigRow((current) => toRow({ ...toConfig(current), autoDownloadModels: enabled }));
122
122
  return toConfig(row);
123
123
  }
124
+ export async function readLastModelName(state) {
125
+ return (await readConfig(state)).lastModelName ?? null;
126
+ }
127
+ export async function writeLastModelName(state, name) {
128
+ await state.updateAppConfigRow((current) => toRow({ ...toConfig(current), lastModelName: name }));
129
+ }
130
+ export async function backfillLastModelName(state, pick) {
131
+ const config = await readConfig(state);
132
+ if (!config.onboardingCompleted || config.lastModelName) {
133
+ return;
134
+ }
135
+ const name = await pick();
136
+ if (!name) {
137
+ return;
138
+ }
139
+ await state.updateAppConfigRow((current) => {
140
+ const latest = toConfig(current);
141
+ return toRow({ ...latest, lastModelName: latest.lastModelName ?? name });
142
+ });
143
+ }
124
144
  export function createAppConfigApi(state, log) {
125
145
  return {
126
146
  getConfig(_) {
@@ -1,3 +1,3 @@
1
1
  import { type MeshPool } from './current-mesh.ts';
2
2
  import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
3
- export declare function createApprovalRulesApi(pool: MeshPool): Pick<CapabilityHandlers, 'listApprovalRules'>;
3
+ export declare function createApprovalRulesApi(pool: MeshPool): Pick<CapabilityHandlers, 'listApprovalRules' | 'removeApprovalRule'>;
@@ -1,4 +1,4 @@
1
- import { listApprovalRules } from '../core/approval-rules.js';
1
+ import { listApprovalRules, removeApprovalRule } from '../core/approval-rules.js';
2
2
  import { requireMesh } from './current-mesh.js';
3
3
  export function createApprovalRulesApi(pool) {
4
4
  return {
@@ -8,6 +8,10 @@ export function createApprovalRulesApi(pool) {
8
8
  rules: await listApprovalRules(mesh),
9
9
  ourMemberId: mesh.ourMemberId ?? undefined
10
10
  };
11
+ },
12
+ removeApprovalRule: async ({ meshId, ruleId }) => {
13
+ await removeApprovalRule(await requireMesh(pool, meshId, { route: 'put-approval-rule' }), ruleId);
14
+ return { ok: true };
11
15
  }
12
16
  };
13
17
  }
@@ -1,9 +1,13 @@
1
1
  import type { LoggerInterface } from '@qvac/logging';
2
2
  import type { AssistantConfigValue } from '../../spec/hyperschema/types.d.ts';
3
- import type { openLocalStore } from '../core/local/index.ts';
3
+ import type { ConfigEntry, openLocalStore } from '../core/local/index.ts';
4
4
  import type { CapabilityHandlers, WatchStream } from '../../spec/capabilities.d.ts';
5
5
  type LocalStore = Awaited<ReturnType<typeof openLocalStore>>;
6
6
  export declare function readConfigAnswer(answer: AssistantConfigValue): AssistantConfigValue;
7
7
  export declare function readConfigFrames(source: WatchStream<AssistantConfigValue>): WatchStream<AssistantConfigValue>;
8
- export declare function createConfigApi(state: LocalStore, log: LoggerInterface | null, onset?: ((key: string) => void) | null): Pick<CapabilityHandlers, 'configGet' | 'configSet' | 'configWatch'>;
8
+ interface ConfigWriteHooks {
9
+ readonly onset?: ((entry: ConfigEntry) => void | Promise<void>) | null;
10
+ readonly beforeSet?: ((entry: ConfigEntry) => void) | null;
11
+ }
12
+ export declare function createConfigApi(state: LocalStore, log: LoggerInterface | null, { onset, beforeSet }?: ConfigWriteHooks): Pick<CapabilityHandlers, 'configGet' | 'configSet' | 'configWatch'>;
9
13
  export {};
@@ -2,7 +2,10 @@ import { Readable } from 'streamx';
2
2
  import { watchable } from './watchable.js';
3
3
  import { frameReadable } from '../frame-readable.js';
4
4
  import { latestFrame } from '../latest-frame.js';
5
- import { configValue, readConfigValue } from '../core/config-value.js';
5
+ import { QUARANTINE_PREFIX, configValue, readConfigValue } from '../core/config-value.js';
6
+ function readable(state, key) {
7
+ return key.startsWith(QUARANTINE_PREFIX) ? Promise.resolve(null) : state.get(key);
8
+ }
6
9
  export function readConfigAnswer(answer) {
7
10
  return { value: readConfigValue(answer) };
8
11
  }
@@ -41,17 +44,18 @@ export function readConfigFrames(source) {
41
44
  source.on('close', onEnd);
42
45
  return frameReadable(output);
43
46
  }
44
- export function createConfigApi(state, log, onset = null) {
47
+ export function createConfigApi(state, log, { onset = null, beforeSet = null } = {}) {
45
48
  return {
46
49
  async configGet({ key }) {
47
- return configValue(await state.get(key));
50
+ return configValue(await readable(state, key));
48
51
  },
49
52
  async configSet({ key, value }) {
53
+ beforeSet?.({ key, value });
50
54
  await state.set(key, value);
51
- onset?.(key);
55
+ await onset?.({ key, value });
52
56
  return { ok: true };
53
57
  },
54
- configWatch: watchable(() => state, async ({ key }) => configValue(await state.get(key)), { name: 'configWatch', log })
58
+ configWatch: watchable(() => state, async ({ key }) => configValue(await readable(state, key)), { name: 'configWatch', log })
55
59
  };
56
60
  }
57
61
  function noop() { }
@@ -1,5 +1,5 @@
1
1
  import type { Capabilities, CapabilityHandlers } from '../../spec/capabilities.d.ts';
2
- export declare const DEVICE_ROUTES: readonly ["listModels", "deleteModel", "loadModel", "unloadModel", "retryModelDownload", "clearModelDownload", "modelCatalogWatch", "modelDownloadsWatch", "customModelsWatch", "previewCustomModel", "addCustomModel", "removeCustomModel", "modelUsers", "modelsWatch", "configGet", "configSet", "configWatch", "setModelPaused"];
2
+ export declare const DEVICE_ROUTES: readonly ["listModels", "deleteModel", "loadModel", "unloadModel", "retryModelDownload", "clearModelDownload", "modelCatalogWatch", "modelDownloadsWatch", "customModelsWatch", "previewCustomModel", "addCustomModel", "removeCustomModel", "modelUsers", "modelsWatch", "configGet", "configSet", "configWatch", "setModelPaused", "skillOauth"];
3
3
  export type DeviceRoutes = Pick<CapabilityHandlers, (typeof DEVICE_ROUTES)[number]>;
4
4
  export interface ForwardingOptions {
5
5
  readonly deviceId: Buffer;
@@ -26,7 +26,8 @@ export const DEVICE_ROUTES = [
26
26
  'configGet',
27
27
  'configSet',
28
28
  'configWatch',
29
- 'setModelPaused'
29
+ 'setModelPaused',
30
+ 'skillOauth'
30
31
  ];
31
32
  function modelRoutes(at) {
32
33
  return {
@@ -47,6 +48,7 @@ function modelRoutes(at) {
47
48
  configGet: (input) => answer(at(input).configGet, 'configGet', here(input)),
48
49
  configSet: (input) => answer(at(input).configSet, 'configSet', here(input)),
49
50
  configWatch: (input) => watched(() => required(at(input).configWatch, 'configWatch')(here(input))),
51
+ skillOauth: (input) => answer(at(input).skillOauth, 'skillOauth', here(input)),
50
52
  setModelPaused: (input) => answer(at(input).setModelPaused, 'setModelPaused', here(input))
51
53
  };
52
54
  }
@@ -1,6 +1,6 @@
1
1
  import type { LoggerInterface } from '@qvac/logging';
2
2
  import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
3
- import type { AssistantCapabilityProfile, AssistantClearModelDownloadRequest, AssistantDeleteModelRequest, AssistantDeleteModelResponse, AssistantCompactChatResponse, AssistantKvCacheDeletionResponse, AssistantListModelsRequest, AssistantLoadModelRequest, AssistantLoadModelResponse, AssistantModelCatalogRevision, AssistantCopySkillResponse, AssistantDeleteSkillResponse, AssistantManagedSkillsResponse, AssistantModelInfoList, AssistantOkResponse, AssistantPushSkillSecretRequest, AssistantSkillCatalogResponse, AssistantSkillFileResponse, AssistantSpeakRequest, AssistantSpeakResponse, AssistantToolCatalogResponse, AssistantDetectLanguageRequest, AssistantDetectLanguageResponse, AssistantTranscribeRequest, AssistantTranscribeResponse, AssistantUnloadModelRequest, AssistantUnloadModelResponse, AssistantModelUsers, AssistantModelUsersRequest } from '../../spec/hyperschema/types.d.ts';
3
+ import type { AssistantCapabilityProfile, AssistantClearModelDownloadRequest, AssistantDeleteModelRequest, AssistantDeleteModelResponse, AssistantCompactChatResponse, AssistantKvCacheDeletionResponse, AssistantQuarantinedSkillKeys, AssistantListModelsRequest, AssistantLoadModelRequest, AssistantLoadModelResponse, AssistantModelCatalogRevision, AssistantCopySkillResponse, AssistantDeleteSkillResponse, AssistantManagedSkillsResponse, AssistantModelInfoList, AssistantOkResponse, AssistantPushSkillSecretRequest, AssistantSkillCatalogResponse, AssistantSkillFileResponse, AssistantSpeakRequest, AssistantSpeakResponse, AssistantToolCatalogResponse, AssistantDetectLanguageRequest, AssistantDetectLanguageResponse, AssistantTranscribeRequest, AssistantTranscribeResponse, AssistantUnloadModelRequest, AssistantUnloadModelResponse, AssistantModelUsers, AssistantModelUsersRequest } from '../../spec/hyperschema/types.d.ts';
4
4
  import type { openLocalStore } from '../core/local/index.ts';
5
5
  import type { Mesh } from '../core/mesh.ts';
6
6
  import { type MeshPool } from './current-mesh.ts';
@@ -78,7 +78,17 @@ interface ApiDeps {
78
78
  nameOf?: NameOf | null;
79
79
  workspaceOf?: ((projectId: string) => Promise<string | null>) | null;
80
80
  pushSkillSecret?: ((request: AssistantPushSkillSecretRequest) => Promise<void>) | null;
81
- onConfigSet?: ((key: string) => void) | null;
81
+ listQuarantinedSkills?: (() => Promise<AssistantQuarantinedSkillKeys>) | null;
82
+ retryQuarantinedSkills?: (() => Promise<AssistantQuarantinedSkillKeys>) | null;
83
+ discardQuarantinedSkills?: ((input: AssistantQuarantinedSkillKeys) => Promise<AssistantQuarantinedSkillKeys>) | null;
84
+ beforeConfigSet?: ((entry: {
85
+ readonly key: string;
86
+ readonly value: unknown;
87
+ }) => void) | null;
88
+ onConfigSet?: ((entry: {
89
+ readonly key: string;
90
+ readonly value: unknown;
91
+ }) => void | Promise<void>) | null;
82
92
  storageRoot?: string | null;
83
93
  skills?: ((agentId?: string | null, modelName?: string | null, options?: SkillOptions) => Promise<unknown>) | null;
84
94
  skillCatalog?: ((agentId?: string | null, modelName?: string | null, options?: {
@@ -10,7 +10,7 @@ import { createChatApi } from './chat.js';
10
10
  import { createChatMoveApi } from './chat-move.js';
11
11
  import { createChatGroupsApi } from './chat-groups.js';
12
12
  import { createChunksApi } from './chunks.js';
13
- import { createAppConfigApi } from './app-config.js';
13
+ import { createAppConfigApi, writeLastModelName } from './app-config.js';
14
14
  import { createConfigApi } from './config.js';
15
15
  import { createDevicesApi } from './devices.js';
16
16
  import { createDiagnosticsApi } from './diagnostics.js';
@@ -46,7 +46,9 @@ export function createApi(deps = {}) {
46
46
  const members = mesh && deps.meshStatus ? createMembersApi(mesh, deps.meshStatus, { state, log }) : null;
47
47
  const folders = state && deps.storageRoot ? new AgentFolders(state, { storageRoot: deps.storageRoot }) : null;
48
48
  const handlers = {
49
- ...(state ? createConfigApi(state, log, deps.onConfigSet ?? null) : null),
49
+ ...(state
50
+ ? createConfigApi(state, log, { onset: deps.onConfigSet, beforeSet: deps.beforeConfigSet })
51
+ : null),
50
52
  ...(state ? createAppConfigApi(state, log) : null),
51
53
  ...(state ? createModelDownloadApi(state, log) : null),
52
54
  ...(state
@@ -61,6 +63,7 @@ export function createApi(deps = {}) {
61
63
  ? createAgentsApi(routed(mesh, 'put-agent'), {
62
64
  deviceId: deps.deviceId ?? null,
63
65
  changed: deps.agentChanged ?? null,
66
+ modelPicked: state ? (name) => writeLastModelName(state, name) : null,
64
67
  keepCopies: deps.agentCopiesKept ?? null,
65
68
  peers: deps.meshStatus ?? null,
66
69
  accountChanges: deps.accountAgents ?? null,
@@ -183,6 +186,9 @@ export function createApi(deps = {}) {
183
186
  unloadModel: deps.unloadModel ?? undefined,
184
187
  modelUsers: deps.modelUsers ?? undefined,
185
188
  clearKvCache: deps.clearKvCache ?? undefined,
189
+ listQuarantinedSkills: deps.listQuarantinedSkills ?? undefined,
190
+ retryQuarantinedSkills: deps.retryQuarantinedSkills ?? undefined,
191
+ discardQuarantinedSkills: deps.discardQuarantinedSkills ?? undefined,
186
192
  deleteChatKvCache: deleteChatKvCache
187
193
  ? ({ chatId }) => deleteChatKvCache(chatId)
188
194
  : undefined,
@@ -103,10 +103,9 @@ async function addMember(pool, { projectOf, nameOf }, { meshId, projectId, membe
103
103
  const { workspace, row } = scope;
104
104
  const batch = workspace.batch();
105
105
  batch.dispatch('set-project-listing', { projectId: row.id, memberId });
106
- const key = await dueProjectKey(workspace.view, memberId, {
107
- projectId: row.id,
108
- seed: project.seed
109
- });
106
+ const sealedBy = workspace.ourMemberId;
107
+ const sealing = sealedBy && { projectId: row.id, seed: project.seed, sealedBy };
108
+ const key = sealing && (await dueProjectKey(workspace.view, memberId, sealing));
110
109
  if (key) {
111
110
  batch.dispatch('put-project-key', key);
112
111
  }