@qvac/harness 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -8,130 +8,356 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-25
+
+### Added
+
+- `setModelIdleTimeout(ms)` frees memory once the device has been idle that
+  long: with no `completion`, `invoke`, `embed`, `transcribe`, `speak`,
+  `speakStream` or `warmModel` call in flight, every idle resident model is
+  unloaded, including the image, music and translation runtimes. The next call
+  loads what it needs again. `0`, the default, is Never, and arms no timer. A
+  turn waiting on a tool or an approval between rounds counts as busy, so it
+  keeps its model. Also on the wire as `set-model-idle-timeout`. (#131)
+
+  ```js
+  await harness.setModelIdleTimeout(30 * 60_000)
+  ```
+
+- `setCustomModels` entries take an optional `label`, the name the user gave
+  the model, and `list()` rows carry it as `label`. The tool-call format is
+  matched against the label as well as the file name, so a custom model
+  registered under an opaque id still gets its family's format. (#124)
+
+- `setCustomModels` entries take an optional `contextLength`, the model's
+  trained window. (#124)
+
+  ```js
+  await harness.setCustomModels([
+    {
+      name: 'custom-7f3a',
+      label: 'Gemma 4 E4B',
+      src: preview.src,
+      contextLength: preview.contextLength
+    }
+  ])
+  ```
+
+### Changed
+
+- A custom model loads with a context of the smaller of 51,200 tokens and its
+  trained `contextLength`, instead of the default. An asked-for context size
+  still wins. (#124)
+
+### Fixed
+
+- `previewModelSource` takes a direct link to one shard of a split `.gguf` as
+  the whole set: `src` is the first part, `sizeBytes` adds up every part, and
+  the label names the count, as in `model.gguf (3 parts)`. A missing part
+  refuses with `not-found` or `unreachable`. (#124)
+
+- `isCached` reports a sharded custom download once every shard is on disk,
+  and `deleteModel` removes all of its shards. (#124)
+
 ## [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.
+- `previewModelSource({ src, mmprojSrc })` checks a Hugging Face link, a direct
+  `.gguf` link or a local path before a host adds it as a custom model. It
+  reads the Hugging Face metadata and the file's GGUF header, never the whole
+  model. The answer is a file to register (`src`, `sizeBytes`,
+  `contextLength`, `architecture`, `sizeLabel`, `taskType`, `license`, `fit`
+  and `fitReasons`), a list of `files` to pick from for a repo that holds
+  several, or `ok: false` with a `refusal` code and a `reason` to show. It is
+  served on the `RemoteHarness` client and on an in-process `Harness`, and its
+  types are exported from the package root. (#121)
+
+  ```js
+  const preview = await harness.previewModelSource({ src: link })
+
+  if (!preview.ok) return showError(preview.reason)
+  if (!preview.src) return pickOneOf(preview.files) // then preview files[i].src
+  if (preview.taskType !== 'llm') return showError('Only an llm runs as a custom model')
+  ```
+
+- `setCustomModels` entries take `taskType` and `expectedSize`, and `list()`
+  returns the registered custom models after the catalog rows, with
+  `registrySource: 'custom'`, `isLoaded`, and an `isCached` that is false
+  until every file is on disk and, when `expectedSize` is set, adds up to it.
   (#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)
+
+  ```js
+  await harness.setCustomModels([
+    {
+      name: 'nanbeige-3b',
+      src: preview.src,
+      projectionSrc: preview.mmprojSrc,
+      taskType: preview.taskType,
+      expectedSize: preview.sizeBytes
+    }
+  ])
+
+  const models = await harness.list({ type: 'llm' })
+  const custom = models.filter((model) => model.registrySource === 'custom')
+  ```
+
+- A `modelsDir` Harness option says where downloads live, so `list()` and
+  `deleteModel` can find a custom model's files. The spawned sidecar sets it
+  from its SDK storage; an in-process `Harness` has to pass it. (#121)
+
+  ```js
+  const harness = new Harness({ modelsDir })
+  ```
+
+### Changed
+
+- `deleteModel(name)` removes the weight and projection a custom model
+  downloaded, where it used to remove nothing. It never touches a local path
+  the user pointed at, and the model stays registered, listed as not cached.
+  (#121)
+
+  ```js
+  const { removed, freedBytes } = await harness.deleteModel('nanbeige-3b')
+  ```
+
+- A custom model name resolves only where an `llm` is loaded, never for
+  another task, and a `setCustomModels` entry whose `taskType` is anything
+  other than `llm` is not registered. An entry without `taskType` is an `llm`,
+  as before. (#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)
+- A turn that preloads a skill with `@skill`, or names an active skill in its
+  prompt, 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 window and failed. (#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)
+- `@qvac/sdk` and `@qvac/inference` 0.20.0. Some addons now ship their
+  prebuilds as per-platform packages (`@qvac/<addon>-<os>-<cpu>`, for
+  `audiogen-ggml` 0.4 and `tts-ggml` 0.9), which the addon names in its
+  `#host-addon` import map, and `@qvac/model-fit` and `@qvac/fabric` join the
+  native graph as deferred addons. A host that packages the addons resolves
+  prebuilds through that map, and exempts the new package names from any
+  install age gate: bun skips a blocked optional dependency without a word,
+  and the prebuild goes missing. (#85)
 - 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
+  per-image split added for QVAC-24156 is gone, since SDK 0.20 carries the
+  upstream fix (llama.cpp #27348) and equal-size still images no longer merge
+  as video frames and abort the encode. This release must not be paired with
+  SDK 0.19, where that crash comes back. `<key>-vision-history-v1` cache
+  directories left by the split are no longer read, and clearing all caches
   removes them. (#116)
+- `@qvac/skills` 0.1.9. The diagrams skill carries every recipe inline, so a 2B
+  model no longer loops on loading a reference file it cannot name. The excel
+  skill routes a chat image to create rather than edit, the Google OAuth routes
+  drop the loopback port, and the Asana skill's first setup step names the
+  Asana MCP app to connect. (#115, #118)
 
 ### 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)
+  reuse a stale cached prefix and condition on the superseded answer. The split
+  kept that chat's cache under a sibling key the host's reclaim never reached.
+  (#116)
 
 ## [0.3.2] - 2026-09-23
 
 ### Changed
 
-- A networked python run's approval prompt lists every host its source names in
-  a URL, or says it names none. On an approved run those hosts (and their `www.`
-  form) are reached without asking. Any other host is asked about through
-  `askUser` before it is resolved, and silence past a minute counts as a no. A
-  host that does not wire `askUser` refuses every unnamed host. (#109)
+- A networked Python run's approval label leads with the hosts its source names
+  in a URL, as `python · network: www.youtube.com …`, or says
+  `network: no host named in the code`. On an approved run those hosts, and
+  their `www.` form, are reached without asking; a subdomain is not. Any other
+  host, such as a CDN a library fans out to, a redirect or a URL built at
+  runtime, pauses the run and is asked about through the completion's
+  `askUser` before its name is looked up. A host allowed once stays allowed
+  for that run, and silence past a minute counts as a no. A host that does not
+  wire `askUser` refuses every unnamed host, and a skip-all run asks nothing.
+  (#109)
+
+  ```js
+  for await (const event of harness.completion({
+    model,
+    agent,
+    messages,
+    approve,
+    // options are ['Allow', 'Deny']; an answer starting with "Allow" allows it
+    askUser: ({ question, options }) => showQuestion(question, options)
+  })) {
+    render(event)
+  }
+  ```
 
 ### Fixed
 
-- A python call reached the network whenever the runtime allowed it, so an
-  auto-run read call, such as a document build that loads an image from a URL,
-  could reach the web without anyone approving it. The network now opens only to
-  a call a person approved or that skip-all allowed. (#108)
-- A timed-out python run on a host with no worker thread spun forever. It is now
-  interrupted at the deadline. (#104)
-- A timed-out python run on the worker could miss its SIGINT, which killed the
-  worker along with the interpreter's state. The interrupt is resent until the
-  run settles. (#112)
-- A python run that failed partway through a save attached the half-written
-  file. A non-zero exit now attaches nothing and reports every declared output in
+- A timed-out Python run spun at full CPU until the process was killed when
+  Pyodide had no worker thread, as for a stowed bundle whose host does not set
+  `QVAC_PYODIDE_WORKER_ENTRY`. It is now interrupted at the deadline, rejects
+  with `Command timed out after <ms>ms`, and the interpreter keeps its state. A
+  blocking call such as a long `time.sleep` still sees the interrupt only once
+  it returns. (#104)
+- A timed-out Python run on the worker thread could miss its SIGINT, so the
+  worker was killed after the grace window along with the interpreter's state.
+  The interrupt is resent every 100 ms until the run settles. (#112)
+- A Python run that failed partway through a save attached the half-written
+  file, and each failing retry attached another copy under the same name. A
+  non-zero exit now attaches nothing and reports every declared output in
   `missingOutputs`. (#110)
 
+### Security
+
+- Python in `exec` reached the network whenever the runtime allowed it,
+  including a call that auto-ran as a read with no approval prompt, so a
+  document build that loads an image from a URL could reach the web without
+  anyone seeing it. The network now opens only to a call a person approved or
+  that skip-all let through, and sandbox mode stays offline. 0.3.1 is affected.
+  (#108)
+
 ## [0.3.1] - 2026-09-23
 
 ### Added
 
 - Python in `exec` reaches the network on Bare: `urllib`, `http.client` and
-  `requests` go through the host's guarded fetch. (#94)
-- `SkillOAuthConfig.verify`: an optional probe a skill manifest declares, so a
-  host can check a fresh token before saving it. It is carried over the wire.
-  (#105)
-- A skill operation may name `response.decode` to turn a provider response into
-  a compact shape, starting with `gmail-message`. (#69)
+  what is built on them, yt-dlp included, work unchanged, and `requests` works
+  through urllib3's emscripten backend. Every request goes through the guarded
+  fetch the web tools use, so each hop is checked before it is sent,
+  credentials do not follow a redirect to another origin, and a response is
+  capped at 100 MB. Where the global `fetch` is not the guarded one, as on
+  Node, Python stays offline, and sandbox mode keeps it offline everywhere. A
+  Python run may now declare `.mp4`, `.webm`, `.m4a` and `.mp3` outputs, each
+  checked by its file signature. (#94)
+- `SkillOAuthConfig.verify`, parsed from a skill manifest's
+  `setup.routes[].oauth.verify` and carried over the wire, so a host can probe a
+  fresh token before saving it. A probe is an https `url` on the same site as
+  the route's `tokenUrl`, an optional `GET` or `POST` `method` and JSON `body`,
+  and `reject` rules. A rule matches a listed `status`, or a 2xx JSON body whose
+  `field` is not `notEqual`, and its `error` names the rejection. A probe that
+  breaks these rules is dropped and the route kept. `SkillOAuthVerify` and
+  `SkillOAuthVerifyRule` are exported. (#105)
+
+  ```js
+  const skills = await harness.skills()
+  const route = skills
+    .find((skill) => skill.name === 'asana')
+    ?.setup?.routes?.find((r) => r.kind === 'oauth')
+
+  // { url: 'https://mcp.asana.com/v2/mcp', method: 'POST',
+  //   body: '{"jsonrpc":"2.0",…}',
+  //   reject: [{ status: [401, 403], error: 'asana_not_mcp_app' }] }
+  const verify = route?.oauth?.verify
+  ```
+
+- A skill operation may name `response.decode` to turn a provider's JSON body
+  into a compact shape before the model sees it, starting with
+  `gmail-message`: the ids and labels, the From, To, Subject, Date, Message-ID
+  and References headers, the snippet, and the body as text, capped at 4000
+  characters. A `gmail-get` request builder joins it. A manifest naming both
+  `pick` and `decode`, or a builder or decoder this harness does not have, is
+  rejected. (#69)
+
+### Changed
+
+- A compiled skill operation whose HTTP method is `GET`, `HEAD` or `OPTIONS` is
+  a read: it auto-runs without an approval prompt, like the same request through
+  `http_request`, and takes no `intent` argument. MCP operations and every other
+  method are still writes that ask. (#69)
+- `@qvac/skills` 0.1.7, now pinned exactly: Gmail reads a message with
+  `gmail_get` instead of telling the model to decode base64, which needs this
+  release's decoder, and Asana rejects a non-MCP app at connect time through
+  a `verify` probe. (#105)
 
 ### Fixed
 
 - A malformed `<tool_call>` left its JSON arguments in the reply. The whole span
-  is now stripped. (#100)
+  is now stripped, and an unclosed one is stripped to the end of the text.
+  (#100)
 - A misspelt, placeholder or repeated `skill` load returned an error the model
-  retried. It now resolves to the file that was meant, or to the already-loaded
-  body. (#101)
-- When the model reached for `pip` or a video tool on the shell path, the
-  redirect it got now names the call that works. (#71)
+  retried until the turn ran out. A placeholder or the skill's own name now
+  reads the body, a near miss of one of its files loads that file, and a repeat
+  is acknowledged without re-reading it. (#101)
+- When the model reached for `pip` or a video tool on the shell path, it was
+  only told what the path is not, and retried the same call. Each refusal now
+  names the call that works, such as `packages: ["requests"]` with the pin a
+  vendored package installs offline under. A missing import names the package
+  that provides it, and `python -c`, a heredoc or bare Python source runs as
+  Python instead of being sent back for a `language` argument. (#71)
 
 ## [0.3.0] - 2026-09-23
 
 ### Added
 
-- `translate` capability: translates text without loading an LLM. The language
-  pair picks the route before anything loads: the TranslatePsy-EuroNano packs for
-  English and nine European languages, per-pair Bergamot models for the other 43,
-  and TranslatePsy-AfriSLM for 16 languages Bergamot has no model for, named by
-  ISO 639-1 or FLORES-200 code. An omitted `from` is detected from the text. (#76)
-- `translationPlanFor`, `NMT_TO_ENGLISH`, `NMT_FROM_ENGLISH`, `EURONANO_LANGUAGES`,
-  `SLM_LANGUAGE_CODES` and `SLM_LANGUAGE_NAMES` exports, so a host can show a
-  language picker or preview a route without a registry lookup (#76)
+- A `translate` capability for `invoke`: it translates text without loading an
+  LLM. The language pair picks the route before anything loads. English and
+  one of nine European languages go through the TranslatePsy-EuroNano packs,
+  the other 43 languages Bergamot serves go through their per-pair models
+  (pivoting through English when neither side is English), and 16 languages
+  Bergamot has no model for go through TranslatePsy-AfriSLM, named by ISO 639-1
+  or FLORES-200 code. An omitted `from` is detected from the text, except for
+  the AfriSLM languages, which need it named. The `tool-result` carries the
+  text, the pair and the `engine` that answered. (#76)
+
+  ```js
+  for await (const event of harness.invoke({
+    capability: 'translate',
+    args: { text: 'The weather is nice today.', to: 'de' }
+  })) {
+    if (event.type === 'tool-result') show(event.result.text)
+    if (event.type === 'error') showError(event.message)
+  }
+  // result: { text, from, to: 'de', engine: 'nmt', pivoted: false }
+  ```
+
+- `translationPlanFor`, `NMT_TO_ENGLISH`, `NMT_FROM_ENGLISH`,
+  `EURONANO_LANGUAGES`, `SLM_LANGUAGE_CODES` and `SLM_LANGUAGE_NAMES` exports,
+  so a host can build a language picker or preview a route without a registry
+  lookup. (#76)
+
+  ```js
+  import { translationPlanFor, SLM_LANGUAGE_NAMES } from '@qvac/harness'
+
+  const plan = translationPlanFor('es', 'ja')
+  // { route: 'nmt', from: 'es', to: 'ja',
+  //   model: 'model.esen.intgemm', pivot: 'model.enja.intgemm' }
+  if ('error' in plan) showError(plan.error)
+  ```
+
 - `enhance: 'never' | 'auto'` on `invoke`. With `'auto'`, an image prompt is
-  rewritten by a model already resident on the device and never triggers a load;
-  `metrics` reports the `route` taken, the model used and the tokens the rewrite
-  spent. Omitting `enhance` behaves as `'never'`. (#77)
+  rewritten by a model already resident on the device, and never triggers a
+  load: with nothing resident, or a rewrite that fails, the run goes direct.
+  `metrics` reports the `route` taken (`direct` or `enhanced`), the
+  `routeModel` used and the tokens the rewrite spent. Omitting `enhance`
+  behaves as `'never'`, which passes the arguments through untouched. (#77)
+
+  ```js
+  for await (const event of harness.invoke({
+    capability: 'image',
+    args: { prompt: 'funny meme' },
+    enhance: 'auto'
+  })) {
+    if (event.type === 'metrics') log(event.route, event.routeModel)
+  }
+  ```
+
+### Changed
+
+- The bundle defers `@qvac/translation-nmtcpp` like the other inference
+  addons, so `prebuilds-manifest.json` now names its prebuilds and a host that
+  assembles them beside the bundle has to include it. It is already a
+  dependency of `@qvac/sdk`. (#76)
 
 ## [0.2.12] - 2026-09-22
 
 ### Fixed
 
-- Sandbox mode refused every `exec` call that installs packages, which broke the
-  pdf, presentations, word and excel skills. Packages the harness vendors now
-  install; one that would fall back to PyPI is still refused. (#91)
+- Sandbox mode refused every `exec` call that installs packages, which broke
+  the pdf, presentations, word and excel skills. A request whose packages are
+  all vendored now installs from the shipped wheels; one that would fall back
+  to PyPI is still refused. (#91)
 
 ## [0.2.11] - 2026-09-22
 
@@ -139,161 +365,483 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Added
 
-- `Harness#invoke({ capability, args })` runs one capability on its own, with no
-  model, dispatch or approval callback. It is a frame on the existing
-  `completion` stream, with the same callbacks and events. (#74)
-- `Harness#detectLanguage({ text, topK })`, the `detect-language` hrpc method and
-  its `RemoteHarness` client: language detection with no model to load (#75)
-- `SkillOAuthConfig` on `SkillSetupRoute.oauth`, parsed from a skill manifest's
-  `setup.routes[].oauth` (#88)
+- `invoke({ capability, args })` runs one capability on its own, with no
+  model, no dispatch and no approval callback: the caller already decided.
+  `image` is the first capability. It is a frame on the existing `completion`
+  stream, so it takes the same `attach`, `progress` and abort signal and emits
+  the same `tool-call`, `tool-result`, `metrics`, `error` and `aborted` events.
+  `metrics` reports `totalTokens: 0`. It is on `Harness` and `RemoteHarness`
+  alike, and optional on `HarnessContract`. (#74)
+
+  ```js
+  for await (const event of harness.invoke({
+    capability: 'image',
+    args: { prompt: 'a lighthouse at dusk', width: 768, height: 512 },
+    attach,
+    progress,
+    signal
+  })) {
+    if (event.type === 'tool-result') showImage(event.result)
+    if (event.type === 'error') showError(event.message)
+  }
+  ```
+
+- `detectLanguage({ text, topK })`, served over hrpc as `detect-language` and
+  on `RemoteHarness`: language detection with no model to load. Without
+  `topK`, or with 1, it answers with the single best match and no
+  probability. Above that it returns ranked candidates with their
+  probabilities, best first, and may return fewer than asked. Text it cannot
+  place answers `und`. (#75)
+
+  ```js
+  const [best] = await harness.detectLanguage({ text })
+  // { code, language }
+
+  const ranked = await harness.detectLanguage({ text, topK: 3 })
+  // [{ code, language, probability }, ...]
+  ```
+
+- `SkillOAuthConfig` on `SkillSetupRoute.oauth`, parsed from a skill
+  manifest's `setup.routes[].oauth` and carried over the wire, so a host can
+  run a skill's OAuth setup from its manifest instead of its own provider
+  table. A route missing `stateKey`, `authUrl`, `tokenUrl` or `tokenAuth`
+  carries no `oauth`. (#88)
+
+### Changed
+
+- `@qvac/skills` 0.1.6: the eight OAuth skills declare their setup routes'
+  OAuth config, the Spotify skill always makes the play call after a search,
+  and the weather skill looks the place up with `weather_lookup`. (#88)
 
 ### Fixed
 
-- `web_fetch` offers file downloads (PDF, Office documents, images) in its
-  description, and `attachDocument` returns the `attachmentId`, `fileName` and
-  `byteLength` it creates, so a downloaded file survives a history fold (#89)
+- Asked to fetch a file, the model tried `http_request` and `exec` before
+  `web_fetch`, and once the file was attached it had no id to read it with.
+  `web_fetch` now offers file downloads (PDF, Office documents, images) in its
+  description, and its result carries the `attachmentId`, `fileName` and
+  `byteLength` it created, so the model can stage the file into `exec` and it
+  survives a history fold. (#89)
 
 ## [0.2.10] - 2026-09-22
 
 ### Added
 
 - `sandboxMode` agent option: an agent with no network access. It withholds
-  every tool that reaches the network, not just web search. (#73)
-- `@qvac/harness/office`: XLSX and PPTX text extraction for Knowledge beside the
-  existing DOCX support, keeping sheets, column positions, cached formula values,
-  slide text, grouped shapes and tables (#83)
+  every tool that reaches the network (the web search, HTTP request and MCP
+  toolsets, including skill operations over HTTP or MCP), not just web search.
+  `exec` stays, but refuses package installs and well-known network commands
+  such as `curl`, `git` and `npm`. That is a guard, not an OS-level sandbox.
+  (#73)
+
+  ```js
+  for await (const event of harness.completion({
+    model,
+    messages,
+    agent: { ...agent, sandboxMode: true }
+  })) {
+    render(event)
+  }
+  ```
+
+- `@qvac/harness/office`: XLSX and PPTX text extraction for Knowledge beside
+  DOCX, through the same bundled Python worker. It keeps sheet names, column
+  positions, cached formula values, slide text, grouped shapes and tables;
+  speaker notes, images and charts are left out. The format comes from the
+  file extension, with `mimeType` as the fallback. `@qvac/harness/docx` is
+  unchanged. (#83)
+
+  ```js
+  import { extractOfficeText, closeOfficeWorker } from '@qvac/harness/office'
+
+  const text = await extractOfficeText(bytes, 'report.xlsx', { signal, mimeType })
+  // at host shutdown, once extractions have settled
+  await closeOfficeWorker()
+  ```
 
 ### Fixed
 
-- A tool call that already failed this turn with the same arguments is answered
-  from its first result instead of running again, so a small model can no longer
-  loop on the same failure (#78)
-- A guessed `auth.tokenCredentialKey` is resolved by URL instead of being refused
-  with an error claiming the skill was not loaded (#72)
+- A small model could loop on the same failing tool call, up to the round
+  cap. A call that already failed this turn with the same arguments is now
+  answered from its first result without running again, until a later round
+  succeeds. Three such answers end the turn's tool rounds. A failure that may
+  pass on retry, such as a timeout, a 5xx, 408 or 429, still runs again, and
+  the tools that can fail that way now say so in a `code` or `status` field on
+  their result. (#78)
+- A guessed `auth.tokenCredentialKey` on `http_request` or `mcp_call` was
+  refused with an error claiming the skill was not loaded. It now resolves to
+  the one connected credential allowed for that URL, and when none is
+  connected the error says so and tells the user to connect it in Skills.
+  (#72)
 
 ## [0.2.9] - 2026-09-22
 
 ### Added
 
-- `captureInferenceCalls` harness option: emits `inference-call` and
-  `inference-sent` events carrying the exact payload of every inference call (#51)
-- The `metrics` event carries the last round's `stopReason`, so a turn cut off by
-  the context window is distinguishable from a complete one (#62)
+- `captureInferenceCalls` on a completion's context: each round then emits an
+  `inference-call` event with the exact payload it is about to send (model,
+  messages, tools, generation params, cache key and prompt prefix), and an
+  `inference-sent` event once it ends, with the tokens it spent, its `outcome`
+  (`completed`, `overflowed` or `failed`) and, on the bundled patched SDK, the
+  slice of `messages` the KV cache let through. An attempt the overflow ladder
+  rejected is still recorded, with its `droppedTurns`. Off unless asked for,
+  since every record carries a whole prompt. The flag and both events are new on
+  the hrpc wire, so the host and the spawned harness both need 0.2.9. (#51)
+
+  ```js
+  for await (const event of harness.completion({ model, messages, captureInferenceCalls: true })) {
+    if (event.type === 'inference-call') record(event.call.round, event.call.messages)
+    if (event.type === 'inference-sent') settle(event.round, event.outcome, event.tokens)
+  }
+  ```
+
+- The `metrics` event carries the last round's `stopReason`, and leaves it out
+  when the SDK reports none. A turn cut off by the context window ends cleanly
+  with `stopReason: 'length'`, so a host can tell it from a complete answer.
+  (#62)
+
+  ```js
+  if (event.type === 'metrics' && event.stopReason === 'length') markTruncated()
+  ```
 
 ### Changed
 
-- The published tarball no longer includes docs, agent files or eval output (#79)
+- The published tarball no longer carries `docs/`, `CLAUDE.md`, `.claude/` or
+  eval output. (#79)
 
 ## [0.2.8] - 2026-09-17
 
 ### Added
 
-- `weather_lookup` tool: looks weather up and leads with the place the service
-  actually resolved, refusing when it disagrees with the country or state asked
-  for, instead of reporting the weather of wherever a nonexistent place landed
-  (#52)
+- `weather_lookup`, a tool that looks weather up on wttr.in by `location` and
+  leads its report with the place the service actually resolved. When that
+  place disagrees with the country or state the user named, it refuses instead
+  of reporting the weather of wherever the geocoder landed: a nonexistent town
+  no longer gets a forecast, and a bare "Rome" the service places in Togo says
+  so. It is offered only once the weather skill is loaded, needs no approval,
+  and the `http-request` toolset switch turns it off. The spawned sidecar
+  registers it; an in-process host adds it to its tools. (#52)
 
-### Fixed
+  ```js
+  import { createWeatherLookupTool } from '@qvac/harness/lib/tools/weather-lookup.ts'
+
+  const harness = new Harness({ tools: [...tools, createWeatherLookupTool()] })
+  ```
+
+### Changed
 
-- `@qvac/skills` 0.1.4: Apple Notes create-note no longer renames a note after
-  creating it, which failed on iCloud accounts and left duplicates (#48)
+- **Breaking:** `currentReleaseLine` from `@qvac/harness/schema/release-tags`,
+  the schema build tooling, is now `currentReleaseVersion`, and returns the
+  full `bare-semver` `Version` rather than a `major.minor` string. A host that
+  imports it imports `currentReleaseVersion` instead and reads the line off
+  the version. (#55)
+
+  ```js
+  // 0.2.7
+  const line = currentReleaseLine(root) // '0.2'
+
+  // 0.2.8
+  const version = currentReleaseVersion(root) // Version 0.2.8
+  const line = `${version.major}.${version.minor}`
+  ```
+
+- `previousReleaseTags` from the same module now counts the newest shipped tag
+  on the line being built as a baseline, not only older lines, so a schema
+  change is checked against the build users are running. Only tags newer than
+  the package version are left out. A host that regenerates its `spec/`
+  against it re-derives hyperschema's version counters once, so expect one
+  regeneration commit after upgrading. (#55, #58)
+- `@qvac/skills` 0.1.4: the Apple Notes create-note operation no longer
+  renames a note after creating it, which failed on iCloud accounts and left
+  duplicate notes behind. (#48)
 
 ## [0.2.7] - 2026-09-16
 
 ### Added
 
-- `@qvac/harness/docx`: DOCX text extraction with the bundled Python runtime,
-  preserving paragraph and table order (#46)
+- `@qvac/harness/docx`: `extractDocxText` pulls a DOCX file's text for
+  Knowledge with the bundled Python runtime, keeping paragraphs and tables in
+  document order, one row per line with cells joined by `' | '`. It takes up to
+  20 MiB and only the shipped wheels, never a network install. Set
+  `QVAC_PYODIDE_CACHE_DIR` to a writable directory first, so the worker seeds
+  its cache from those wheels and works offline. A bundled host also sets
+  `QVAC_PYODIDE_WORKER_ENTRY` and `QVAC_PYTHON_WHEELS_DIR` to its staged
+  worker and wheels. (#46)
+
+  ```js
+  import { extractDocxText, closeDocxWorker } from '@qvac/harness/docx'
+
+  const text = await extractDocxText(bytes, 'notes.docx', { signal })
+
+  // at shutdown, once outstanding extractions have settled
+  await closeDocxWorker()
+  ```
+
+### Fixed
+
+- A Python run whose signal aborted while it waited for another run to finish
+  is no longer started. (#46)
 
 ## [0.2.6] - 2026-09-15
 
 ### Added
 
-- `completionModelCap` harness option, default 1: a completion model waits for a
-  live run to release its model instead of loading beside it (#41)
-- `writeClient` and `writeCapabilities` take a `CallSiteOptions` argument whose
-  `optionalRequests` names the requests the generated client may omit (#44)
+- `completionModelCap`, default 1: how many completion models may be resident
+  at once. It is a `HarnessOptions` field, and rides the `llm` config through
+  `spawnHarness` and `harnessChild`. (#41)
+
+  ```js
+  const harness = spawnHarness({
+    entry,
+    sdkStorage,
+    llm: { contextSize: 8192, completionModelCap: 2 }
+  })
+  ```
+
+- `writeClient` and `writeCapabilities` from `@qvac/harness/schema/generate`
+  take an options argument whose `optionalRequests` names the request types a
+  caller may omit: the generated client sends `{}` for them and the generated
+  capability types mark the input optional. Left out, only `@assistant/empty`
+  is optional, as before. A set you pass replaces that default, so include it
+  if you still want it. `writeClient` still takes an export name as a string.
+  (#44)
+
+  ```js
+  import { writeClient, writeCapabilities } from '@qvac/harness/schema/generate'
+
+  const optionalRequests = new Set(['@assistant/empty', '@assistant/mesh-scope'])
+  writeClient(builder, 'spec/calls.js', { exportName: 'engineClient', optionalRequests })
+  writeCapabilities(builder, 'spec/capabilities.d.ts', { optionalRequests })
+  ```
+
+### Changed
+
+- A completion that needs a different model no longer loads it beside one a
+  live run is holding. It waits for that run to release its model, for up to
+  five minutes, and then loads anyway rather than failing. A `warmModel` call
+  waits two seconds at most, and skips the warm if no room was made. (#41)
 
 ## [0.2.5] - 2026-09-14
 
 ### Added
 
-- `HarnessOptions.gpuStats`: a host that already has the GPU reading can pass it
-  and skip the probe (#36)
+- A `gpuStats` option on `spawnHarness`, `harnessChild` and `HarnessOptions`.
+  A host that already has the GPU reading passes it, and the harness skips its
+  own probe. Left out, the harness probes for itself. (#36)
+
+  ```js
+  import { spawnHarness } from '@qvac/harness/lib/spawn.ts'
+
+  const harness = spawnHarness({
+    entry,
+    sdkStorage,
+    gpuStats: {
+      memory: { totalBytes: os.totalmem() },
+      gpu: { devices: [{ name: 'NVIDIA RTX 4070', videoMemoryBytes: 12884901888 }] }
+    }
+  })
+  ```
 
 ### Fixed
 
-- On a Linux snap the harness exited about a second after `open`, in a loop. GPUs
-  are now enumerated in a short-lived child process. (#36)
-- On Windows, an image request after a presentation stuck on "Loading … into
-  memory": Pyodide's boot no longer touches the process streams (#34)
+- On a Linux snap the harness exited about a second after `open`, and the
+  supervisor respawned it in a loop: the boot-time capability probe created a
+  second GPU-info instance beside the SDK's own. On Linux and Windows under
+  Bare, GPUs are now enumerated in a short-lived child process, which gives up
+  after 5 seconds and reports no GPU. (#36)
+- On Windows, asking for an image after a presentation left the chat stuck on
+  "Loading … into memory". Pyodide's boot opened the process streams from the
+  Python worker thread, which blocked the image-model loader's progress. Boot
+  now never touches them; a run's own output capture is unchanged. (#34)
 
 ## [0.2.4] - 2026-09-12
 
 ### Added
 
-- The sidecar entry is published, so a host can spawn the engine without the
-  prebuilt bundle and with its native addons resolved at matching versions (#31)
+- `@qvac/harness/worker/stow-entry.mjs`: the sidecar entry, published so a
+  host running from inside `node_modules` spawns the engine without the
+  prebuilt bundle. Every native addon then resolves beside the JS that calls
+  it, from one install. With the bundle, the addons come from the host's own
+  install, and a version skew there hangs the child on boot rather than
+  throwing: `@qvac/core` 0.1.2 shipped that way. The bundle stays published
+  for a host that relocates the code out of `node_modules`. (#31)
+
+  ```js
+  import { harnessChild } from '@qvac/harness/lib/spawn.ts'
+
+  const entry = new URL(import.meta.resolve('@qvac/harness/worker/stow-entry.mjs')).pathname
+  const spec = harnessChild(entry, { runner, skillsDir, wheelsDir, sdkStorage: storage.sdk })
+  ```
 
 ## [0.2.3] - 2026-09-12
 
+### Added
+
+- `schema/generate` emits `writeStream` on the generated `HandlerFrames`, so a
+  duplex handler's frames type without a local widening. (#29)
+
+### Changed
+
+- On Android and iOS, `resolveStorage` keeps models under the app's own
+  persistent root instead of the device HOME, which an app cannot write.
+  Desktop and Snap are unchanged, and `overrides.models` still wins. (#29)
+
+  ```js
+  import { resolveStorage } from '@qvac/harness/storage'
+
+  const storage = resolveStorage('prod')
+  // mobile: <persistent root>/.qvac/models
+  storage.sdk.models
+  ```
+
 ### Fixed
 
-- Every `./lib/tools/*` subpath is published. Only the 12 that `qvac-core` used
-  were, so the mobile worklet's file tools could not resolve. (#29)
+- Every `./lib/tools/*` subpath is published. The tarball listed only the ones
+  `qvac-core` imports, so the mobile worklet's file tools (`file-glob`, `grep`,
+  `read-files`, `create-documents`, `edit-documents`, `fs/scope`) failed with
+  `PACKAGE_PATH_NOT_EXPORTED`. 0.1.1 to 0.2.2 are affected. (#29)
 
 ## [0.2.2] - 2026-09-11
 
 ### Fixed
 
-- The lockfile no longer resolves a stale nested `@qvac/inference` (#27)
+- A stale lockfile entry gave `@qvac/sdk` its own nested `@qvac/inference`
+  0.19.1, beside the patched 0.19.0 the harness pins. The bundle is built from
+  the pinned copy alone again. (#27)
 
 ## [0.2.1] - 2026-09-11
 
 ### Fixed
 
-- The generated wire spec matches the schema it is built from (#25)
+- The generated wire spec in 0.2.0 stamped the fields it added (`downloaded`
+  on a download event and as a model status, and `kvCacheKey`) with schema
+  version 7, the version 0.1.2 already shipped. They are version 8 now, so the
+  spec matches the schema it is built from. (#25)
 
 ## [0.2.0] - 2026-09-11
 
 ### Added
 
-- Chat compaction when the context window fills (#22)
-- Per-chat KV cache invalidation and reclaim (#22)
-- Notifications delivered from device-local state (#22)
-- A log of the tool prompt, and cheaper model-facing tool schemas (#22)
-- The target sample rate threaded through the Bare audio decoder (#22)
+- `deleteKvCache(kvCacheKey)` deletes one chat's KV cache, every file kept
+  under that key, where `clearKvCache()` deletes them all. It is safe on a key
+  still in use: the next turn under it primes from scratch. It rides a new
+  `delete-kv-cache` hrpc route, and resolves with `{ status }` like
+  `clearKvCache`. (#22)
+
+  ```js
+  // the cacheKey the chat's completions ran under
+  const result = await harness.deleteKvCache(cacheKey)
+  if (result.status !== 'success') log(result.error)
+  ```
+
+- A download's `complete` event carries `downloaded`, `true` when bytes were
+  fetched and `false` when the model was already on disk. An image model's
+  `model` events report `loading` rather than `downloading` when it is cached,
+  and a new `downloaded` status once a fetched one has loaded, so a host that
+  switches over `status` has one more case. (#22)
+
+  ```js
+  for await (const event of harness.download({ model })) {
+    if (event.type === 'complete' && event.downloaded) notifyDownloaded(model)
+  }
+
+  harness.on('model', ({ model, status }) => {
+    if (status === 'downloaded') notifyDownloaded(model)
+  })
+  ```
+
+- `ToolDefinition.prompt`: an optional compact `description` and `parameters`
+  the model is shown in place of the full ones, which still validate the call.
+  `exec` and `skill` ship one, so every turn spends less of the prompt on
+  their schemas. (#22)
+- `CONTEXT_OVERFLOW_MESSAGE` is exported, the message a turn fails with when
+  it does not fit the model's context window, so a host can tell that failure
+  apart and compact the chat. (#22)
+
+  ```js
+  import { CONTEXT_OVERFLOW_MESSAGE } from '@qvac/harness'
+  ```
+
+- With `QVAC_HARNESS_LOG=1`, each turn logs `sdk tool definitions`: the tool
+  schemas it sent, largest first, with each one's size and the skill that
+  granted it. (#22)
 
 ### Changed
 
-- QVAC SDK 0.19: `@qvac/inference` serves the Bare condition behind a new `#sdk`
-  import alias (#22)
-- `bare-http1` is pinned to 4.5.9 (#24)
+- `@qvac/sdk` 0.19.0, pinned exactly. Under Bare the SDK is now served by
+  `@qvac/inference` 0.19.0, through a new `#sdk` import alias.
+  `@qvac/audiogen-ggml` joins the deferred addons, so `prebuilds-manifest.json`
+  names it and the host provides it too. (#22)
+- Image and music generation schemas reach the model once their skill's
+  instructions are loaded, not as soon as the skill is enabled. Loading the
+  skill unlocks them within the same turn, at the cost of one cache re-prime
+  on that round. (#22)
+- `@qvac/skills` 0.1.3: the weather skill keeps the place exactly as the user
+  wrote it, asks back on an ambiguous city name, and reports a failed lookup
+  instead of a temperature it never received. (#22)
+- `bare-http1` is pinned to 4.5.9, as a dependency and as an override.
+  (#22, #24)
 
 ## [0.1.2] - 2026-09-11
 
 ### Fixed
 
-- `@qvac/harness/sdk-storage` and `#sdk-config-loader` failed to resolve under
-  Bare: the tarball carried only the Node loader (#20)
+- `@qvac/harness/sdk-storage` and `@qvac/harness/sdk-config-loader` failed to
+  resolve under Bare with `MODULE_NOT_FOUND`: the tarball carried only the Node
+  loader behind `#sdk-config-loader`, so `configureSdkStorage()` could not run
+  on Bare. Both loaders ship now. 0.1.1 is affected. (#20)
+
+  ```js
+  // Bare: loads again, nothing else changes
+  import { configureSdkStorage } from '@qvac/harness/sdk-storage'
+  ```
 
 ## [0.1.1] - 2026-09-10
 
 ### Added
 
-- A compiled library surface (`dist-lib/`, JavaScript and declarations), so the
-  package's exports import without shipping TypeScript source (#18)
+- The library surface ships compiled: `dist-lib/` carries JavaScript and a
+  `.d.ts` for every export, so `@qvac/harness` and its subpaths import from
+  npm under plain Node or Bare, with no TypeScript source or type-stripping
+  loader. Export keys are unchanged, `.ts`-suffixed deep paths included, so a
+  host that took the library from the repository switches to the package
+  without editing a specifier. Of `./lib/tools/*`, only the paths `qvac-core`
+  imports are published. (#18)
+
+  ```js
+  import { harnessChild, spawnHarness } from '@qvac/harness/lib/spawn.ts'
+  import { AbortedError, raceAbort } from '@qvac/harness/race-abort'
+  ```
 
 ## [0.1.0] - 2026-09-10
 
 ### Added
 
-- First release of the QVAC engine as `@qvac/harness`: the prebuilt
-  `harness.bundle` a host spawns, its runtime content (skills from `@qvac/skills`
-  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.4.0...HEAD
+- First release of the QVAC engine as `@qvac/harness`. The tarball is the
+  prebuilt `dist/harness.bundle`, one bundle for every platform, and the
+  generated `dist/harness.cjs` a host requires to spawn it as a bare-sidecar
+  process. It spawns and does not import: the export map points at library
+  source the tarball leaves out, so a host takes `spawnHarness`,
+  `harnessChild` and the transport from the repository until a compiled
+  surface ships. (#13)
+
+  ```js
+  const harness = require('@qvac/harness/dist/harness.cjs')
+
+  const { ipc, sidecar, exit } = await harness.start(args)
+  ```
+
+- `dist/prebuilds-manifest.json` names every native prebuild directory the
+  bundle defers, keyed by its path relative to the bundle. The host assembles
+  those beside the bundle from its own `node_modules`, and installs the
+  `@qvac` inference addons and `pyodide` alongside. (#13)
+- Skills come from `@qvac/skills` 0.1.2, a content-addressed bundle the
+  harness materializes at runtime. The Python wheels the tool runtime installs
+  ship in `wheels/`, each pinned by hash in `wheels/manifest.json`. (#13, #15)
+- GPU stats are read through `bare-gpu-info`, so every dependency installs from
+  the public npm registry. (#12)
+
+[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/tetherto/qvac-harness/compare/v0.4.0...v0.5.0
 [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