@qvac/harness 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -8,6 +8,59 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-24
+
+### Added
+
+- `Harness#previewModelSource({ src, mmprojSrc })`: checks a Hugging Face link,
+  a direct `.gguf` link or a local path without downloading it. Returns the
+  download link, size, context length, architecture, license, task type and a
+  fit verdict, lists the files of a repo that holds several, or refuses with a
+  reason. (#121)
+- `setCustomModels` takes `taskType` and `expectedSize`. Only `llm` custom
+  models are registered, and a custom name never resolves for another task.
+  (#121)
+- `list()` returns custom models with their task, size, and whether they are
+  loaded and on disk; the new `modelsDir` option tells the harness where
+  downloads live. (#121)
+- `Harness#deleteModel(name)` removes what a custom model downloaded, never a
+  local path the user pointed at. (#121)
+
+### Fixed
+
+- A turn that preloads a skill with `@skill` no longer caches the inlined
+  SKILL.md body under the chat's KV key. Each such turn left about 7k tokens
+  stranded in the cache, until a later turn overflowed the context. (#120)
+
+## [0.3.3] - 2026-09-24
+
+### Changed
+
+- `@qvac/sdk` 0.20.0. Some addons now ship their prebuilds as per-platform
+  packages (`@qvac/<addon>-<os>-<cpu>`, e.g. `audiogen-ggml` 0.4, `tts-ggml`
+  0.9), and `@qvac/model-fit` and `@qvac/fabric` join the native graph. A host
+  that bundles the harness resolves prebuilds through each addon's
+  `#host-addon` map, defers the new addons, and exempts the platform packages
+  from any install age gate. (#85)
+- `@qvac/skills` 0.1.8: the diagrams skill carries every recipe inline, so a
+  2B no longer loops on a second `skill` load for a reference file it cannot
+  name (QVAC-24436, QVAC-24502); the excel skill routes a chat image to create,
+  not edit; the Google OAuth routes drop the loopback port. (#115)
+- A user message with several images reaches the SDK as one turn again. The
+  per-image split added for QVAC-24156 is gone: SDK 0.20 carries the upstream
+  mtmd fix (llama.cpp #27348), so equal-size still images no longer merge as
+  video frames and abort the encode. `<key>-vision-history-v1` cache
+  directories left by the split are no longer read; clearing all caches
+  removes them. (#116)
+
+### Fixed
+
+- Retrying or regenerating in a chat that held a multi-image message could
+  reuse a stale cached prefix, because the split kept that chat's cache under a
+  key the host never deletes. (#116)
+- `@qvac/skills` 0.1.9: the Asana skill's first setup step names the Asana MCP
+  app to connect. (#118)
+
 ## [0.3.2] - 2026-09-23
 
 ### Changed
@@ -240,7 +293,9 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   and the hash-pinned Python wheels), and `prebuilds-manifest.json` naming the
   native addons it defers (#13, #15)
 
-[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/tetherto/qvac-harness/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/tetherto/qvac-harness/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/tetherto/qvac-harness/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/tetherto/qvac-harness/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/tetherto/qvac-harness/compare/v0.2.12...v0.3.0

package/README.md

@@ -48,6 +48,140 @@ dir, ...) are the ones `worker/harness-sidecar.mjs` documents in this repo. The
 in-house hosts don't call this directly — they use the repo's library surface
 (`harnessChild` under bare-supervisor), which owns that argv contract.
 
+## Custom models
+
+A host can let its users add a GGUF the catalog does not carry: a Hugging Face
+link, a direct link to a `.gguf` file, or a local path. The harness checks the
+source, runs it by the name the host registers it under, lists it next to the
+catalog and deletes what it downloaded. Which custom models a device has is the
+host's state; the harness keeps only the set it was last given.
+
+The calls below are on the client `spawnHarness` returns (a `RemoteHarness`) and
+on an in-process `Harness` alike.
+
+### Preview a source before adding it
+
+`previewModelSource` reads the source's Hugging Face metadata and the first
+megabyte of the file. It never downloads the model.
+
+```js
+const preview = await harness.previewModelSource({
+  src: 'https://huggingface.co/bartowski/Nanbeige_Nanbeige4.2-3B-GGUF/resolve/main/Nanbeige_Nanbeige4.2-3B-IQ2_M.gguf',
+  mmprojSrc: undefined // a vision model's projection, checked with it
+})
+
+// {
+//   ok: true,
+//   src: 'https://huggingface.co/.../Nanbeige_Nanbeige4.2-3B-IQ2_M.gguf',
+//   sizeBytes: 1868506272,
+//   contextLength: 262144,
+//   architecture: 'nanbeige',
+//   sizeLabel: '3B',
+//   taskType: 'llm',
+//   license: 'apache-2.0',
+//   fit: 'unknown',
+//   fitReasons: ['...why the fit is unknown']
+// }
+```
+
+A preview is one of three answers:
+
+- **A file**: `ok: true` with `src`, the download link to register. A Hugging
+  Face page link is resolved to its `resolve/` url.
+- **A choice**: `ok: true` with `files: [{ src, label, sizeBytes }]` and no
+  `src`, for a repo that holds several weights. Split shards are one entry and
+  projections are left out. Preview the chosen `files[i].src` again.
+- **A refusal**: `ok: false` with `refusal` and a `reason` ready to show. The
+  refusals are `invalid-source`, `not-found`, `private`, `gated`, `web-page`,
+  `unreachable`, `not-gguf`, `not-a-model` (a projection or LoRA adapter),
+  `no-model-files` and `invalid-projection`.
+
+```js
+if (!preview.ok) return showError(preview.reason)
+if (!preview.src) return pickOneOf(preview.files)
+```
+
+`taskType` says what the model does: `llm`, `embeddings`, `speech-to-text`,
+`text-to-speech` or `image-generation`. It comes from the Hugging Face pipeline
+tag, then the card's and the file's tags, then the architecture. The preview
+reports it for any model and refuses none for its task, so the host decides
+what may be added. Only an `llm` runs as a custom model today:
+
+```js
+if (preview.taskType !== 'llm') {
+  return showError(`This is a ${preview.taskType} model. Custom models run as the text model only.`)
+}
+```
+
+`fit` is `likely-fits`, `likely-too-large` or `unknown`, and `fitReasons` says
+why. It comes only from the SDK, for a file whose sha256 its catalog knows, so
+most custom files are `unknown`. It is never a reason to refuse.
+
+`sizeLabel` is the file's own `general.size_label` as written (`0.6B`, `3B`,
+`30B-A3B`), and is absent when the file records none.
+
+### Register the set
+
+`setCustomModels` replaces the whole set. Send it on start and whenever the
+host's store changes; the client sends the last set again after a reconnect.
+
+```js
+await harness.setCustomModels([
+  {
+    name: 'nanbeige-3b',
+    src: preview.src,
+    projectionSrc: preview.mmprojSrc,
+    taskType: preview.taskType, // 'llm'; an entry for another task is not registered
+    expectedSize: preview.sizeBytes
+  }
+])
+```
+
+A registered name loads like a catalog model wherever an `llm` name is taken,
+and never resolves for another task. A missing `taskType` means `llm`.
+`expectedSize` is what `isCached` compares the downloaded files against.
+
+### List them
+
+`list` returns custom models after the catalog rows, under the same `type` and
+`cachedOnly` filters:
+
+```js
+const models = await harness.list({ type: 'llm' })
+const custom = models.filter((model) => model.registrySource === 'custom')
+
+// {
+//   name: 'nanbeige-3b',
+//   type: 'llm',
+//   registryPath: 'https://huggingface.co/.../Nanbeige_Nanbeige4.2-3B-IQ2_M.gguf',
+//   registrySource: 'custom',
+//   isCached: false,
+//   isLoaded: false,
+//   supportsImages: false,
+//   expectedSize: 1868506272
+// }
+```
+
+`registryPath` is the model's `src`, and `supportsImages` is true when it has a
+projection. `isCached` means every file is on disk and, when `expectedSize` is
+known, their sizes add up to it, so a partial download is not cached. A local
+path is checked where it is. A downloaded file is looked for at the path the SDK
+gives a single-file http download under the models cache dir, which the spawned
+sidecar knows from `sdkStorage.models`; an in-process `Harness` needs
+`new Harness({ modelsDir })` for it. A sharded or archive url always reads as
+not cached.
+
+### Delete a download
+
+```js
+const { removed, freedBytes } = await harness.deleteModel('nanbeige-3b')
+```
+
+For a custom model this removes the weight and projection it downloaded, and
+never a local path: those are the user's files. The model stays registered and
+lists as not cached, ready to download again. Like a catalog delete, it does not
+unload a model that is running.
+
 ## Office extraction
 
 Hosts can supply the bundled Python extractor to their document pipeline: