@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/README.md

@@ -1,542 +1,349 @@
-# @qvac/harness
+<p align="center">
+  <img src="docs/assets/ducks.png" alt="" width="200">
+</p>
+
+<h1 align="center">@qvac/harness</h1>
+
+<p align="center">
+  <b>The agent harness for local models</b>
+  <br>
+  Tools, agents, sandboxes and resumable runs on your own device
+</p>
+
+<p align="center">
+  on-device GGUF models &middot; Bare and Node &middot; agents that hand off and delegate &middot;
+  parallel tools and runs &middot; sandboxed exec &middot; crash-proof sidecar &middot;
+  resume after process death
+</p>
+
+<p align="center">
+  <a href="#how-it-works">How it works</a> &middot;
+  <a href="#features">Features</a> &middot;
+  <a href="#plugins">Plugins</a> &middot;
+  <a href="#examples">Examples</a> &middot;
+  <a href="#host-it">Host it</a> &middot;
+  <a href="#development">Development</a>
+</p>
 
-The QV.AC inference engine: `generate(context)` over the QVAC SDK — completions,
-embeddings, transcription, image and music generation — plus the tool runtime
-skills execute in (Python via Pyodide, web search/fetch, MCP, filesystem). It
-knows nothing about the app, hyperdb or sync: inference in, events out.
-
-It runs as a supervised child process (or Bare thread on mobile) that a host
-spawns and talks to over hrpc — crash isolation for free, death is the exit
-itself. See [bare-supervisor](https://github.com/tetherto/bare-supervisor) for
-the supervision contract.
-
-## The published package
+```sh
+npm i @qvac/harness
+```
 
-The published package ships the library and its runtime content, not a prebuilt
-engine:
+```ts
+import { Harness, QWEN_35_2B } from '@qvac/harness'
 
-- `dist-lib/` — the compiled library and its declarations. The package exports
-  resolve to it; the TypeScript source stays in the repository.
-- `worker/harness-sidecar.mjs` — the sidecar entry a host stows into its own
-  bundle, and `worker/stow-entry.mjs`, the same entry as a plain file for a
-  host that spawns it straight from its install
-- the hash-pinned Python `wheels/` the tool runtime consumes (skills come from
-  [`@qvac/skills`](https://github.com/tetherto/qvac-skills), a content-addressed
-  bundle this package materializes at runtime)
+const harness = new Harness()
+const messages = [{ role: 'user', content: 'Reply with one word: hi' }]
+for await (const event of harness.completion({ model: QWEN_35_2B, messages })) {
+  if (event.type === 'content') {
+    process.stdout.write(event.text)
+  }
+}
 
-A host that stows the harness defers the `@qvac` inference addons
-(`scripts/addon-externals.cjs` lists them), so they resolve from real files
-beside the bundle, and ships everything stow offloads there: prebuilds, and
-pyodide's data and the wheels, which the harness names as assets. A target that
-embeds assets instead cannot run python.
+await harness.close()
+```
 
-## Spawning
+That is the whole API surface for a chat: **context in, events out.** The model is a GGUF that the
+QVAC SDK runs on this device: no server and no API key, and the prompt never leaves it.
 
-`spawnHarness` spawns an entry as a bare-sidecar process and hands back a
-client over hrpc:
+## How it works
 
-```js
-import { spawnHarness } from '@qvac/harness'
-
-const harness = spawnHarness({ entry, sdkStorage })
+```
+  your app                           @qvac/harness  (in process, a child process, or a Bare thread)
+ ┌────────────┐  completion(context) ┌──────────────────────────────────────────────────────────┐
+ │            │ ───────────────────► │  agent ──► prompt ──► model (QVAC SDK, llama.cpp)        │
+ │  UI        │                      │    ▲                       │ tool calls                  │
+ │            │ ◄─────────────────── │    │                       ▼                             │
+ │  approve() │   content, tool-call │    │   guards ──► approve? ──► tools, plugins, agents    │
+ └────────────┘   transfer, metrics  │    └────────── results ◄───────────┘   (one round)      │
+                                     └──────────────────────────────────────────────────────────┘
 ```
 
-`entry` is the host's own stowed bundle, or `@qvac/harness/worker/stow-entry.mjs`
-resolved from its install. The argv slots the entry reads (skills dir, sdk
-storage, model config, wheels dir, ...) are the ones
-`worker/harness-sidecar.mjs` documents; `harnessChild` does the same under
-bare-supervisor.
+A completion is a loop of **rounds**. In each round the model answers or calls tools. Every call is
+checked against its schema and the run's grants, sorted into a read or a write, sent to your
+`approve` if it writes, then run, and its result goes back to the model. The run ends when the model
+answers, a budget runs out, or it hands the conversation to another agent.
 
-## Custom models
+The loop is a state machine (`lib/machine/`), and every step is journaled. So a run can pause for
+approval, survive the process dying, and pick up where it stopped. `bun run resume` kills a run at
+its approval and resumes it; see [The loop is a state machine](examples/README.md#the-loop-is-a-state-machine).
 
-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.
+**Built for small models.** A 2B model makes mistakes a cloud model does not. The harness repairs
+broken tool-call markup, coerces arguments to their schema, re-asks when the model describes a call
+instead of making it, trims long tool output and spills the rest to a file the model can read, and
+folds old turns into a summary when the context fills. The KV cache is reused across rounds and
+runs, so a long chat does not prefill its whole history again.
 
-The calls below are on the client `spawnHarness` returns (a `RemoteHarness`) and
-on an in-process `Harness` alike.
+## Features
 
-### Preview a source before adding it
+### Tools you control
 
-`previewModelSource` reads the source's Hugging Face metadata and the first
-megabyte of the file. It never downloads the model.
+A tool is a plain object. You decide what is a read and what is a write; writes go through `approve`.
 
-```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
-})
+```ts
+const stock: ToolDefinition = {
+  name: 'stock',
+  description: 'Units in stock for one SKU',
+  toolset: null,
+  parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
+  effect: () => 'read',
+  // reads marked concurrent run side by side in one round
+  concurrent: true,
+  execute: (args) => Promise.resolve({ content: String(inventory[String(args.sku)] ?? 0) })
+}
 
-// {
-//   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']
-// }
+harness.completion({ model, messages, tools: [stock], approve: (call) => askTheUser(call) })
 ```
 
-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, and a direct link to one
-  shard of a split model to its first part, sized as the whole set.
-- **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)
-```
+Built-in tools read and edit files only inside folders you grant (`grantedDirs`,
+`grantedWriteDirs`), and never inside the app's own storage. They also read, edit and create Word,
+Excel, PowerPoint and PDF files on device, in TypeScript, with no Python and no cloud.
+
+### Large tool sets, on demand
 
-`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:
+Mark a tool `defer: true` and the model sees only its name, grouped under `group`, until it calls
+`tool_search` to load it. The loaded schema is appended to the history, so the prompt prefix stays
+cached; an MCP server takes `defer: true` for all its tools. A 2B with fifty tools no longer reads
+fifty schemas every round.
 
-```js
-if (preview.taskType !== 'llm') {
-  return showError(`This is a ${preview.taskType} model. Custom models run as the text model only.`)
+```ts
+const lookup: ToolDefinition = {
+  ...stock,
+  name: 'warehouse_lookup',
+  defer: true,
+  group: 'warehouse'
 }
 ```
 
-`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.
+### Agents that hand off
 
-### Register the set
+An agent is a prompt, tools and skills, and may name its own `model`. Give it `handoffs` and it can
+pass the conversation on: here a health question goes to an agent on MedPsy, a medical model. Each
+hop is its own run, with its own `runId`, and emits a `transfer` event.
 
-`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,
-    label: 'Nanbeige 4.2 3B', // what the user calls it
-    contextLength: preview.contextLength // the window it was trained on
+```ts
+const triage = {
+  id: 'triage',
+  bio: 'You route each request to the right agent.',
+  handoffs: [
+    { id: 'office', description: 'Word, Excel and PDF documents' },
+    { id: 'health', description: 'Symptoms, medicines and wellbeing' }
+  ]
+}
+const agents = {
+  office: {
+    bio: 'You write and edit documents.',
+    handoffs: [{ id: 'triage', description: 'Anything that is not a document' }]
+  },
+  // a medical model of its own; the others run on the run's model
+  health: { model: MEDPSY_1_7B, bio: 'You answer health questions clearly.' },
+  triage
+}
+for await (const event of harness.completion({ model, agent: triage, agents, messages })) {
+  if (event.type === 'transfer') {
+    console.log(`${event.from} -> ${event.to}: ${event.reason}`)
+  } else {
+    render(event)
   }
-])
-```
-
-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.
-`label` is the name to show. The harness also reads the model family from it
-(Qwen, Gemma, LFM and so on) to pick the tool-call format, so a model whose id
-and file name don't carry the family still gets the right one.
-`contextLength` caps the context a custom model loads with by default, so a
-model trained on 40,960 tokens loads with 40,960 rather than the 51,200
-default. A context size the caller asks for still wins.
-
-### 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,
-//   isLoading: false,
-//   supportsImages: false,
-//   expectedSize: 1868506272,
-//   label: 'Nanbeige 4.2 3B',
-//   taskType: 'llm'
-// }
+}
 ```
 
-`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 download is looked for in the
-folder the SDK keeps its shards in, and is cached once every shard is there.
+### Agents as tools
 
-Every row, catalog or custom, carries `taskType`: what the model is for, in the
-vocabulary a preview uses, so a Models screen groups by task rather than by
-addon. `whisper` and `parakeet` are both `speech-to-text`, and an addon with no
-task of its own is `other`.
+`delegate` lets an agent send several self-contained tasks to subagents and get every answer back.
+They run on the same loaded model, as many at once as `delegateTool` is given `slots` and the
+harness has. A subagent sees only its task, and cannot delegate or hand off.
 
-### Delete a download
+```ts
+import { Agent } from '@qvac/harness/agent'
 
-```js
-const { removed, freedBytes } = await harness.deleteModel('nanbeige-3b')
+const explorer = { id: 'explorer', bio: 'You answer one question about the code.' }
+const base = { model, agent: explorer, messages: [], grantedDirs: [projectDir] }
+const delegate = Agent.delegateTool(harness, base)
+harness.completion({ model, messages, tools: [delegate], grantedDirs: [projectDir] })
 ```
 
-For a custom model this removes the weight and projection it downloaded,
-including every shard of a sharded one, 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.
-
-### Load and unload a model
-
-```js
-import { QWEN_35_4B } from '@qvac/harness'
+### Hand the hard parts to Claude Code
 
-const { loaded } = await harness.loadModel({ model: QWEN_35_4B, agent: { ctxSize: 8192 } })
-const row = (await harness.list({ cachedOnly: true })).find((model) => model.name === QWEN_35_4B)
-// row.isLoaded === true, and the next completion with the same agent reuses it
+The same `delegate` tool can reach agents outside the harness: Claude Code, Codex, or anything that
+speaks ACP. Each task runs in a fresh process in the run's granted folder, and asks your `approve`
+first.
 
-const { unloaded } = await harness.unloadModel({ model: QWEN_35_4B })
+```ts
+import { ExternalAgents } from '@qvac/harness/plugins/external-agents'
+
+const targets = ExternalAgents.targets({
+  dir: agentsHome,
+  targets: [
+    {
+      name: 'claude',
+      description: 'Claude Code, for a hard change that needs a stronger model',
+      protocol: 'claude',
+      command: '/usr/local/bin/claude',
+      // your own Claude Code sign-in and settings; leave it out to run isolated on an API key
+      login: 'user'
+    }
+  ]
+})
+const delegate = Agent.delegateTool(harness, base, { targets })
 ```
 
-`loadModel` loads a downloaded model ahead of use, under the key a request for it
-would load under, so the first request does not load it again. Pass the agent a
-chat model will run for, since its context size and KV cache types are part of
-that key. Chat, embedding, speech and transcription models stay loaded; image and
-music models load for each generation and are refused.
-
-A chat model loaded this way is pinned. It does not count against
-`completionModelCap`, so several can be loaded at once, and a request loading
-another model leaves it in place. A request or a manual load for the same model
-under other settings replaces its idle copy rather than loading a second one. A
-manual load never unloads another model to fit: `{ loaded: false, reason: 'memory' }` means the
-SDK's `assessModelFit` estimate says it would not fit beside what is loaded, so
-unload one first. A request always gets its model, though: when that would not
-fit, pinned models no reply is using give way, oldest first. Image or music generation and an idle
-unload still clear every idle chat model, pinned or not.
-
-```js
-const big = await harness.loadModel({ model: QWEN_36_27B, agent: { ctxSize: 262144 } })
-if (big.reason === 'memory') showNotice('Unload a model first')
-```
+### Plans and goals
+
+`plan: true` gives an agent `update_plan`, a checklist it sees after every round. A `goal` keeps the
+run going until every step is done or a budget runs out. `planMode` refuses writes until the user
+approves the plan.
 
-`unloadModel` waits for any request holding the model to finish, then unloads
-every copy of it. `unloaded` is false when a request still held it after the
-wait, so a caller that wants the model gone at once stops those requests first.
-Both change `isLoaded` in the next `list()`. `isLoading` is true on a row from
-the moment a load of its model starts, whoever asked for it (a request,
-`warmModel` or `loadModel`), until the model is ready or the load fails; it is
-read off the pool, so a host keeps no count of its own. A model loading again
-under other settings while a copy of it is resident reads `isLoaded: true` and
-`isLoading: true` at once. The `model` event carries `catalogChanged` at each
-edge a `list()` re-read would show: the `loading` that starts a load, the
-`ready` or `error` that ends it, and `unloaded`. Progress ticks between them do
-not. A load that ends without the model in memory reports
-`error` with the reason in `message`: it failed, or a suspend or close cancelled it.
-An image, music or translation model loads for each generation and never reads
-`isLoading: true`; a speech, transcription or embedding model loads under its
-source rather than its row name, so its row reads `false` for now. A load or an
-unload counts as a call in flight for
-[`setModelIdleTimeout`](#freeing-memory-when-idle), and one that lands during an
-idle unload waits for it, so a load never loads a second copy and an unload
-answers once the memory is free.
-
-`bun run model-residency` (`bare examples/model-residency/run.ts`, with
-`QVAC_MODEL_CACHE_PATH` pointing at the models) runs these calls against the
-models already on disk and prints what each step changed. It never downloads.
-
-## Freeing memory when idle
-
-```js
-await harness.setModelIdleTimeout(30 * 60_000)
+```ts
+const agent = { id: 'lead', bio: 'You are the lead engineer.', plan: true }
+harness.completion({ model, agent, messages, goal: { objective: 'All tests pass', rounds: 30 } })
 ```
 
-Once no call has been in flight for that long, every idle resident model is
-unloaded, and the next call loads what it needs again. The clock covers the
-whole device: any call resets it, whichever model it uses. `0`, the default, is
-Never.
+### Steer a run while it works
 
-## Office extraction
+Send turns into a running completion. A steer lands at the next tool boundary; a follow-up continues
+the run after its answer.
 
-Hosts can supply the bundled Python extractor to their document pipeline:
+```ts
+async function* input() {
+  yield { mode: 'steer' as const, text: 'Use the v2 endpoint instead' }
+}
+harness.completion({ model, messages, input: input() })
+```
 
-Set `QVAC_PYODIDE_CACHE_DIR` to a writable directory before calling the API,
-including from source and compiled-package consumers. The worker seeds this
-cache from shipped wheels; without it, Pyodide can try downloading packages.
+### Parallel
 
-```js
-import { extractOfficeText, closeOfficeWorker } from '@qvac/harness/office'
+Concurrent reads in one round run side by side. `slots` lets one loaded model decode several
+completions at once, each with its own context: on the 2B, four requests at `slots: 4` decode about
+30% more tokens a second in all, and each starts in about 0.2 s instead of queueing for 2 s.
 
-const text = await extractOfficeText(bytes, 'report.xlsx', { signal, mimeType })
-// At host shutdown, after outstanding extractions have settled:
-await closeOfficeWorker()
+```ts
+const harness = new Harness({ slots: 2 })
+const [a, b] = await Promise.all([ask(harness, 'Summarize A'), ask(harness, 'Summarize B')])
 ```
 
-DOCX preserves paragraph and table order. XLSX includes sheet names, nonempty rows,
-cached formula results and formula text when no cached result exists. PPTX includes
-slide text, grouped shapes and tables in slide order; speaker notes, images and charts
-are not extracted. Legacy XLS/PPT formats are unsupported. File extensions select the
-format, with `mimeType` as a fallback when the name has no recognized Office extension.
+### Sandboxed code
 
-The extractor accepts up to 20 MiB and requires the shipped Python wheels. With the
-cache configured, extraction uses those wheels offline. A host that stows the harness ships them
-with what stow offloads beside the bundle; `QVAC_PYTHON_WHEELS_DIR` names another directory.
-Source checkouts prepare wheels with `bun run vendor:wheels`.
+`exec: true` gives the model a shell, and plugins decide where it runs: under macOS Seatbelt, in a
+VM, or as JavaScript in QuickJS with no files or network. Python runs in Pyodide. For real coding
+work, `CodingPlugin` adds a shell that keeps its place, background jobs and `write_file`, run
+inside Seatbelt on macOS.
 
-The existing `extractDocxText` and `closeDocxWorker` exports from `@qvac/harness/docx`
-remain available. Both entry points share the same Python worker and cache.
+```ts
+const harness = new Harness({
+  exec: true,
+  plugins: [new SeatbeltSandbox({ preset: 'workspace-write', network: false }), new QuickJs()]
+})
+```
 
-## Development
+### Runs that survive a crash
+
+Spawned with `spawnHarness`, the harness runs as a supervised child process, so a llama.cpp crash
+kills the AI and never the app. Every step of a run is journaled; after the process dies, send the
+same `runId` with `resume: true` and the run carries on. See [Resuming a completion](docs/resuming.md).
+
+### Know how fast it is
+
+Every completion ends with a `metrics` event: prefill and decode tokens per second, time to first
+token, per round and per run. Each loaded model reports the engine's own fit verdict and its device
+and host bytes in `diagnostics().models`. See [Speed stats](docs/speed-stats.md). Accuracy is measured on real
+benchmarks (BFCL, τ²-bench, Terminal-Bench) in [examples/bench](examples/bench/README.md).
+
+## Plugins
+
+A plugin is an instance you pass in `plugins`. Its options are its constructor's argument, and the
+host grants its reads there too: `new Weather({ read: ['weather_lookup'] })`. A plugin never grants
+itself.
+
+| Plugin                                                | Adds                                                                                             |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [`ExternalAgents`](plugins/external-agents/README.md) | Claude Code, Codex or any ACP agent as a `delegate` target                                       |
+| [`WalkieTalkie`](plugins/walkie-talkie/README.md)     | Two-way comms with agents and people on other machines, over Hyperswarm                          |
+| [`RunReport`](plugins/run-report/README.md)           | A run as a flowchart played back step by step, with why; records through `onStep`, not `plugins` |
+| [`CodingPlugin`](plugins/coding/README.md)            | A shell that keeps its place, background jobs, `write_file`                                      |
+| [`LspPlugin`](plugins/lsp/README.md)                  | Definitions, references, symbols and diagnostics from language servers                           |
+| [`McpPlugin`](plugins/mcp/README.md)                  | The tools of any HTTP MCP server                                                                 |
+| [`CodeMode`](plugins/code-mode/README.md)             | `run_code`: a script that calls the other tools                                                  |
+| [`QuickJs`](plugins/quickjs/README.md)                | JavaScript for `exec`, with no files or network                                                  |
+| [`Python`](plugins/python/README.md)                  | Python for `exec`, in Pyodide                                                                    |
+| [`SeatbeltSandbox`](plugins/sandbox-macos/README.md)  | `exec`'s shell under macOS `sandbox-exec`                                                        |
+| [`VmShell`](plugins/sandbox-vm/README.md)             | `exec`'s shell in a VM with no network or disk                                                   |
+| [`CommandHooks`](plugins/command-hooks/README.md)     | The command hooks of a Claude Code `settings.json`                                               |
+| [`Knowledge`](plugins/knowledge/README.md)            | Search over the user's documents                                                                 |
+| [`WebSearchPlugin`](plugins/web-search/README.md)     | Web search across several engines                                                                |
+| [`Speech`](plugins/speech/README.md)                  | Transcription, text to speech, and MOSS voice cloning and dialogue                               |
+| [`Image`](plugins/image/README.md)                    | Image generation and editing                                                                     |
+| [`Music`](plugins/music/README.md)                    | Music generation                                                                                 |
+| [`TranslationPlugin`](plugins/translation/README.md)  | Translation on device                                                                            |
+| [`Weather`](plugins/weather/README.md)                | Weather lookup                                                                                   |
+| [`ObsidianRoute`](plugins/obsidian/README.md)         | `obsidian …` commands against a vault                                                            |
+
+Each plugin is imported from `@qvac/harness/plugins/<folder>`. Writing your own takes one object:
 
-```
-bun install
-bun run lint          # prettier + lunte + tsc
-bun run test          # brittle, node and bare lanes
-bun run build:schema  # regenerates spec/ (wire-compat rewind once v* tags exist)
-bun run build:bundle  # stows the sidecar entry into dist/, to prove it still stows
-```
+```ts
+import { Harness, PLUGIN_API_VERSION, type HarnessPlugin } from '@qvac/harness'
 
-## Engine layout
+const clock: HarnessPlugin = {
+  name: 'clock',
+  api: PLUGIN_API_VERSION,
+  setup: () => ({ tools: [timeTool] })
+}
 
-`lib/machine/` contains `completion/**`, `engine.ts`, `errors.ts`, `index.ts`, `replay-output.ts`,
-`stable-stringify.ts`, and `guards.ts`. The run-log layer is in `lib/run-log/`:
-`protocol.ts`, `protocol-types.ts`, `history-codec.ts`, `run-journal.ts`,
-`persisted-actor.ts`, `replay.ts`, and `patch.ts`.
+const harness = new Harness({ plugins: [clock] })
+```
 
-The completion graph has 24 states and 61 transitions. Reproduce these
-counts with `examples/bench/graph-metrics.ts`.
+`setup` returns tools, hooks, services and `exec` contributions. See the
+[plugin framework](lib/plugins/README.md) and a [custom plugin](examples/custom-plugin/README.md).
 
-The schema baseline rewinds `spec/` against this repo's `v*` release tags and
-skips loudly while none exist. Dependency `overrides` pin the resolutions the
-engine is validated against — keep them aligned with direct specs, npm refuses
-a mismatch on publish.
+## Examples
 
-## License
+Each runs on a local model under `QVAC_MODEL_CACHE_PATH` (`~/.qvac/models` by default).
+`test/examples.ts` proves code-assistant, subagents, handoffs, parallel and custom-plugin on a
+scripted model; host needs a spawned Bare child and a model, so it has no test. More in
+[examples/](examples/README.md).
 
-See [LICENSE](./LICENSE.md).
+| Run                      | Shows                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| `bun run code-assistant` | [A coding team](examples/code-assistant/README.md): plan, subagents, review, Claude Code |
+| `bun run subagents`      | A lead handing one file to each subagent, four reading at once                           |
+| `bun run handoffs`       | A triage agent handing a memo to an office agent, and a health question to one on MedPsy |
+| `bun run parallel`       | Three tools in one round, and two runs on one model                                      |
+| `bun run custom-plugin`  | [A third-party plugin](examples/custom-plugin/README.md): tools, a hook, a service       |
+| `bun run host`           | Hosting the harness as a sidecar, the way a desktop app does                             |
 
-## Resuming a completion
+## Host it
 
-The harness emits resumable steps to a host-owned log. Direct `Harness.completion()` runs without
-that host log work normally, but cannot recover after process death. For remote runs, pass a
-`HostRunLog` to `connectHarness(...).completion()` and reuse the same `runId` when reconnecting.
-The peer must advertise `hostRunLogVersion: 1`.
+Run it in your process with `new Harness()`, or as a supervised sidecar, so a model crash never
+takes down your app:
 
 ```ts
-const request = { runId: 'draft-42', model, messages, agent, runLog }
-for await (const event of remote.completion(request)) {
-  // Save the run ID and render completion events.
-}
+import { spawnHarness } from '@qvac/harness'
 
-// begin() returns the saved boot for this run. connectHarness resumes from it and sends the
-// same request identity; supply current callbacks, tool configs, and filesystem grants again.
-for await (const event of remote.completion({ runId: 'draft-42', resume: true, runLog, approve })) {
-  // Handle run-resumed, round-reset, content, tool activity, and paused.
-}
+const harness = spawnHarness({ entry, sdkStorage })
 ```
 
-`HostRunLog.begin(runId)` acquires one exclusive generation and returns its compact boot, if the
-run already exists, plus a 32-byte `digestKey`. Each `append(runId, generation, step)` must durably
-commit the whole `EngineStep`—its `seq`, expected logical record length, and records—in one
-transaction. The client waits for that commit before continuing. `release(runId, generation)` fences
-late appends from the ended connection. A host may export its authenticated records for inspection;
-the harness does not fetch storage or decrypt a host's log itself.
-
-`hostAppendTimeoutMs` (default 5000) bounds that wait; it applies in full even to a resume issued
-after the run's own deadline has passed. A spawned host raises it via the `runLog` start payload
-when its appends (e.g. a large first append on resume) can take longer than the default.
-
-Cancellation, iterator disposal, suspension, shutdown, and remote disconnect pause a run. A
-`paused` event ends that stream without making the run terminal. Resume retains completed tool
-results; time spent paused does not count against the run's deadline. A `round-reset` event identifies
-the unfinished round. Ordinary resets carry no `replacedTypes`; only the terminal replay reset
-(when resuming) lists the output kinds to replace. Both replace content and thinking. Text and
-tool events carry run/round identities; tool events also carry their call identity. Completed runs
-replay their final answer and metrics without loading a model.
-
-An unfinished write produces `recovery-required` with an `operation` containing its ID, name,
-resolved arguments, and effect. A write that the pause stopped before it started runs again. Reconcile the external result, then supply exactly that operation's
-resolution on resume:
+The sidecar speaks the same `completion(context)` over hrpc. [`@qvac/core`](https://github.com/tetherto/qvac-core)
+takes it unchanged to run agents across your devices; see its
+[Integrating a harness](https://github.com/tetherto/qvac-core#integrating-a-harness).
 
-```ts
-remote.completion({
-  runId: 'draft-42',
-  resume: true,
-  model,
-  messages,
-  agent,
-  recovery: [{ operationId: operation.id, decision: 'result', result: confirmedResult }],
-  runLog,
-  approve
-})
+## Reference
 
-// If re-execution is appropriate, explicitly authorize it instead:
-// recovery: [{ operationId: operation.id, decision: 'retry' }]
-```
+- [Hosting](docs/hosting.md): what the package ships, spawning, freeing memory, office extraction.
+- [Architecture](docs/architecture.md): the engine layout and each module's API.
+- [Resuming a completion](docs/resuming.md): the host run log, process death, the tool-call grammar.
+- [Custom models](docs/custom-models.md): run a GGUF the catalog does not carry.
+- [Speed stats](docs/speed-stats.md) and [benchmarks](examples/bench/README.md).
+- [Decisions](docs/decisions/INDEX.md): why the harness is built the way it is.
 
-A retry can repeat an external effect. Receipts prevent replay of completed operations; they do
-not provide transactions or exactly-once effects in external systems. Missing runtime callbacks or
-a model that cannot load leave the run paused with a recovery reason. For these runtime/read
-reasons, restore the dependencies and resume without a `recovery` resolution. A tool that is gone
-or whose schema changed since the pause ends the run with an error, because no resolution can
-bring the old tool back. Stale resolutions and attempts to change the original conversation or
-model are rejected.
-
-A round can pause with one call's arguments redacted, whether or not a sibling call in the same
-round already landed or was already dispatched. Resuming refuses with `PENDING_ARGS_REDACTED`
-instead of replaying the redacted call. Its `recoveryOperationIds` lists every call the round still
-needs settled before it can proceed: a dispatched write not yet resolved (redacted or not), or a
-call whose real arguments exist only in the redacted snapshot, whether dispatched as a read or
-never dispatched at all. A plain call that was never redacted and never dispatched is not listed;
-it simply runs when the round resumes. Settle any listed operation with `decision: 'result'` and
-the known outcome. `decision: 'skip'` is also available when the host knows a redacted operation
-did not land, or for a read; it records a readable placeholder body,
-`{ skipped: true, reason: 'not executed; arguments unavailable after resume' }`, never the literal
-`undefined`. For a dispatched redacted write, `skip` asserts the call never landed; if the host
-skips a write that did land, the model sees "not executed" and may issue it again. It remains
-refused for a dispatched write whose arguments are available. The `retry` decision re-dispatches a
-call still pending; it is refused once that call already has a settled result, for a call never
-dispatched at all, and for a dispatched call whose arguments were redacted, which re-raises
-`PENDING_ARGS_REDACTED` instead of retrying blind. Settling every listed operation finishes the
-round; the landed write is never repeated, though a redacted read may run again. When no operation
-can be reconciled this way, the error's `forkAt` gives the last log length that never held redacted
-arguments as real ones, and `forkSafe` says whether forking there is actually safe: `false` means a
-write whose intent starts at or after `forkAt` has an unknown outcome — its result already landed, or it was dispatched
-and never resolved — so a fork could repeat it and the host should resolve `recoveryOperationIds`
-instead. `forkRun(sourceCore, targetCore, { at: forkAt, runId })` copies the log up to that point
-under a new `runId`, and the round reruns from there.
-
-Tool definitions are checked again on resume, including their function source. A tool whose
-behavior depends on values captured in a closure must supply and update `policyVersion` when
-those values change; function source cannot reveal them. The `exec` and `http_request` factories
-accept this value as an option; `exec` also fingerprints its static path and Python settings.
-
-Tool configuration values are not stored in the log; a digest verifies that the caller supplies
-the same configuration on resume. Credentials embedded in those values must currently remain
-unchanged. Credentials managed through `setCredentials()` or runtime callbacks can be refreshed
-without changing the request.
-
-For host-owned logs, resume uses the boot returned by `begin()` and does not require the peer's
-local `completionRecovery` capability. A transport `done` frame only means the stream ended; it
-does not mean the run succeeded. Run-log and machine versions must match. XState restore accepts
-older stable patches in the installed minor; future patches, other minors, and prereleases are
-rejected. The first checkpoint and child actor snapshots are trusted inputs; diagnostic replay does
-not verify actor effects or the initial context.
-
-`connectHarness(transport, { runLogReleaseTimeoutMs })` bounds host lease cleanup to 5 seconds
-by default. A rejected, throwing, or timed-out release is logged without replacing the completion
-outcome. The host must keep generation fencing active until release actually settles; a cleanup
-timeout does not authorize another writer.
-
-Each run's metadata contains a JSON-only definition of the machine, including state hierarchy,
-initial states, tags, invoked actors, and named transition guards/actions. Checkpoints and deltas
-also carry the exact event, source/target state IDs, fired guard names, and action names observed in
-XState's transition trace. The inspector displays these recorded traces and can replay state/context
-at the same machine and XState versions; event-triggered guard/action traces are re-evaluated and
-must match the recorded trace exactly, or replay reports a divergence. Eventless traces (no
-triggering event, e.g. `always` transitions) are not replay-verified; the inspector marks each such
-line `[eventless; not replay-verified]`. A version mismatch, legacy log, or prefix selection skips
-replay and leaves the stored snapshot and trace authoritative. The checked-in [completion
-graph](./docs/statecharts/completion-machine.mmd) is generated from the same machine definition and
-CI rejects a stale artifact.
-
-Export records from the host, then inspect a selected logical record or physical core length:
+## Development
 
 ```sh
-bare examples/run-log/inspect.ts <records.json> --context <recordIndex>
-bare examples/run-log/view.ts <records.json> report.html --limit <recordIndex>
+bun install
+bun run lint          # prettier + lunte + tsc
+bun run test          # brittle, node and bare lanes
+bun run build:schema  # regenerates spec/
 ```
 
-Logical record index, engine step sequence, and physical storage length are different positions;
-host exports can include the mapping. The CLI reads exported records only. The host remains
-responsible for remote lookup, authentication, decryption, and sharing access.
-
-`@qvac/harness/run-log-inspect` is the library behind that CLI: `inspectRun(core, opts)` yields the
-same lines the `inspect.ts` example prints, and `renderRunLogHtml(core, opts)` renders the HTML
-report `view.ts` writes. A host imports either directly instead of shelling out to the examples,
-passing a `MachineLog` adapter or an envelope whose `records()` method returns an async iterable
-of `{ recordIndex, stepSeq, physicalLength, record }` entries. A raw records array or parsed JSON
-envelope must first be adapted; the CLI's `recordsCore` helper shows this conversion. Options are
-`recordLimit` (an exclusive logical index), `contextRecord`, `physicalLength`, and
-`contextPhysicalLength`.
-
-The completion machine is internal: its state names are part of the run-log format, not the API.
-Hook consumers observe `runPause` and `runResume` for a run that can resume. A run with no run-log
-store cannot resume, so a pause ends it and `runEnd` reports `aborted` (the caller aborted) or
-`abandoned` (the consumer stopped iterating).
-
-## Tool-call markup grammar
-
-A tool-call block opens with `<function`, up to 64 ASCII whitespace characters, `=`, up to 64
-more ASCII whitespace characters, a name, up to 64 ASCII whitespace characters, and `>`. Tags are
-case-insensitive, except in the legacy nested reading below. An executable name is 1–64
-non-whitespace characters other than `<` or `>`; persistence also recognizes longer names so an
-oversized call cannot bypass redaction. A parameter uses the same form with `parameter` in place
-of `function`, and ends at the first case-insensitive
-`</parameter>`. A function block ends at the first case-insensitive `</function>`. Anything after
-that closer is prose and cannot extend the call, including more parameters or closers.
-
-Text that does not form a complete opener and closed block is prose. In particular, empty names,
-overlong executable names, bare parameter tags, and function-tag examples without a matching
-closer are neither executed nor hidden from the displayed answer. Stray function closers, including
-`</FUNCTION>`, also stay visible. A function opener inside a function block or a parameter opener
-inside a parameter value makes that block ambiguous, and persistence redacts it conservatively.
-A block with a nested function opener keeps the legacy recovery reading: the first lowercase
-`<function=` with no whitespace before `=` names the call. The text between `=` and `>` is limited
-to 64 characters before the name is trimmed. It runs with complete lowercase
-parameters up to the first lowercase `</function>` within that block. That reading ignores other
-function openers, so `<function=a><function=login>…` runs `a`,
-`<FUNCTION=a><function=login>…` and `<function =a><function=login>…` run `login`, and
-`<FUNCTION=a><FUNCTION=login>…` runs nothing. Likewise,
-`<function=x><function= login ><parameter=path>p</parameter></function>` runs `x` with `path: "p"`
-when `x` is a known tool. An unclosed parameter, such as `<parameter=key>S</function>`, contributes
-no argument and does not itself make the function block ambiguous. Persistence still redacts its
-value when the name is a credential field or a registered sensitive parameter, including in prose.
-
-## Run-log data and privacy
-
-The harness redacts structured values before it sends a durable step to the host. String or object
-values under exact credential field names are redacted. Numeric values under known credential
-names are also redacted; generic `token` counts and `secret` flags are preserved. Registered tool
-parameters marked `sensitive: true` are redacted regardless of name or value type. Known names include `db_password`, `GITHUB_TOKEN`,
-`openai_api_key`, `client_password`, and `client_passphrase` (case, underscores, and hyphens
-are normalized).
-Name-based redaction is best effort: provider key names such as `ANTHROPIC_API_KEY`, `GH_TOKEN`,
-and `PGPASSWORD` are not covered, and a bare `token` argument (e.g. a pagination cursor) is
-redacted and lost on resume just like a real secret. The durable way to mark a value as a secret,
-regardless of its name, is the schema's `sensitive: true` annotation.
-Encoded assistant tool calls are redacted when history crosses persistence. Within one live process,
-a model's next request still sees its own prior call's real arguments, because that history lives
-only in the actor's memory. A **resumed** run has no such memory: its context is rebuilt from the
-persisted (redacted) log, so the model's first request after resume sees `[redacted]` for any tool
-call it made before the run was interrupted, not the original argument; that argument cannot be
-recovered. The model sees that prior call as well-formed markup with the literal `"[redacted]"`
-value, not an error; a model that re-issues such a call runs it with that literal placeholder.
-A persisted `raw` or `rawCall` of 4,096 characters or more is rebuilt from its (redacted) arguments
-even when nothing is sensitive, so it may differ byte-for-byte from the live call's `rawCall`.
-Shorter unchanged text stays identical to the original.
-Other arbitrary strings, tool results, and prose are preserved. Persisted machine
-history can reference matching original request messages by index and materializes to the same
-messages on resume and inspection — this applies to the caller-supplied conversation the run
-started from, which is never redacted, not to arguments the model generated mid-run. Hosts must
-treat free text and results as confidential and
-protect their log with encryption and access control. The host's `digestKey` verifies request
-identity and never enters a run record.
-
-A pending tool call whose arguments were redacted cannot be executed on resume and is rejected.
-A literal `[redacted]` supplied by the user is not enough to trigger that check. Tool configuration
-values are not stored in the run log; a keyed digest verifies that the caller supplies the same
-configuration on resume. Credentials managed through `setCredentials()` or runtime callbacks can
-be refreshed without changing the request identity.
+## License
+
+See [LICENSE](./LICENSE.md).