@qvac/harness 0.2.5 → 0.2.6

package/.claude/skills/kvcache/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: kvcache
+description: Reason about the QVAC SDK KV cache, the context window and ContextOverflow in @qvac/harness — including why the sliding window (n_discarded) and dynamic tools (toolsMode) were retired. Use when touching prompt-cache keys, the overflow ladder, TTFT regressions, context-overflow errors, cache invalidation on retry/regenerate, or when debugging "the model forgot the conversation". Read this BEFORE proposing any caller-side history eviction.
+---
+
+# KV cache + context window
+
+Read **[docs/kvcache-reference.md](../../../docs/kvcache-reference.md)** — how it
+works and the rules for using it. The summary below is just enough to stop the
+common wrong turns.
+
+This repo owns the cache: `lib/capabilities/completion.ts` (the `kvCache` key,
+the round loop, the overflow ladder), `lib/context-window.ts`,
+`lib/models/kv-cache.ts` and `lib/models/model-pool.ts`. The *prompt* side —
+folding a chat's history so it fits — is `@qvac/core`'s `lib/compaction.ts`;
+see its **compaction** skill before proposing anything that shrinks history.
+
+## The one thing to internalise
+
+Three state sets exist and are **never reconciled**:
+
+| Layer | State | Keyed by |
+| --- | --- | --- |
+| caller (`@qvac/core`) | message **list** (shrinks only on an overflow retry) | chat |
+| SDK | message **count** (`savedCount`) | cache file path |
+| addon | token **positions** (`nPast`) + the on-disk `.bin` | cache key |
+
+Almost every bug here is drift between those three, not context pressure.
+`savedCount` means "already sent", never "still resident": nothing below the
+SDK reports what it evicted. That is what made the retired sliding window and
+dynamic-tools trim fatal, and it is the test for any new eviction idea.
+
+## The knobs (two)
+
+- `history`: the full history goes to `completion()`; the SDK computes the delta.
+- `cacheKey: 'chat-<chatId>'` — set by the caller, consumed here at
+  [lib/capabilities/completion.ts](../../../lib/capabilities/completion.ts).
+  An accepted diagram repair primes under a child of it (`chat-<chatId>/r<n>`),
+  so deleting the chat key reclaims every generation.
+
+Nothing else. `n_discarded` and `toolsMode` are gone from the stack, not just
+unset.
+
+**No client-side token math, ever.** Use the SDK's real `cacheTokens` /
+`promptTokens` / `generatedTokens` from `completion()` stats, and react to the
+typed `ContextOverflowError`. Never estimate chars-per-token, never reserve a
+response budget. To A/B the cache, drop `cacheKey` locally.
+
+If you encounter `RESERVED_FOR_RESPONSE`, a chars-per-token estimator,
+`windowHistoryToFit`, or `toolsThatFit` anywhere, that is retired code — not the
+shipping path, and none of it should come back.
+
+## Retired knobs
+
+Both were dropped on 2026-08-20 and have since been deleted upstream. Kept here
+as bug shapes, not as options.
+
+- **Sliding window (`n_discarded`).** SDK 0.19 dropped it from the `loadModel`
+  schema (rejected at validation) and addon 0.48 removed sliding outright. Why
+  it had to go: a slide was invisible to the SDK — it recorded the turn's full
+  message count and next sent `history.slice(savedCount)`, so the discarded span
+  was gone from the KV, never re-sent, and the model silently lost the middle of
+  the chat. While sliding was possible the tool block also travelled with every
+  turn (`toolBlockEvictable`, ~331 tokens for a 4-tool agent). A full window is
+  now a normal end state, recovered by the ladder and by the caller's fold.
+- **Dynamic tools (`toolsMode: 'dynamic'`).** SDK 0.18 deleted the key (its
+  parser rejects it); the addon dropped `tools_compact` after 0.39.4. It was a
+  no-op on every shipped model — the addon gate is exact-arch `qwen3`, ours are
+  `qwen35`/`qwen36` — while the SDK still sliced as-if-dynamic: the previous
+  answer was duplicated into the KV every turn and, on a cold cache, only the
+  last exchange was sent instead of overflowing. Static placement is the only
+  mode: `history.slice(savedCount)`, full history on a cold cache at TTFT cost
+  only, which is also what makes the overflow ladder effective.
+
+Full history: [2026-08-20-kvcache-static-placement](https://github.com/tetherto/qvac-app/blob/main/docs/decisions/2026-08-20-kvcache-static-placement.md),
+still in `tetherto/qvac-app`.
+
+## Hard facts that trip people up
+
+- **A slice at or above `ctx_size` can never be admitted.** Nothing is decoded
+  yet, so there is nothing to evict — and nothing evicts anyway.
+- **Overflow is a normal end state:** every long chat legitimately reaches ctx,
+  recovered by the ladder and by the caller's fold for any window at or above
+  4,096. Also legitimate: the current prompt alone exceeds ctx, a tool result
+  alone exceeds ctx, or a device that has never run this chat getting the whole
+  history (the cache is **device-local**). Anything else is a drift bug.
+- **A thrown overflow keeps the cache** (SDK 0.19,
+  [qvac#4163](https://github.com/tetherto/qvac/pull/4163)): a prefill
+  `ContextOverflowError` or an addon pre-mutation refusal releases the turn and
+  the committed `.bin` survives. What still destroys it: a turn that hits the
+  ceiling **mid-generation** (addon `stopReason=contextOverflow`, surfaced as
+  `length`) is not committed — its file is unlinked and the next turn
+  cold-primes from history.
+- **The tool block is not in the primed prefix** (since 0.17.1): the prime is
+  the system prompt alone. The block travels with the first turn that renders it
+  (the SDK requires a user message before believing it landed) and is skipped
+  once `toolBlockCached` is recorded at commit. It is never trimmed back out, so
+  `configHash` hashes the system prompt **plus the full tool definitions** — any
+  tool-set, description, or parameter change re-keys the file and costs a cold
+  prime. A skill activation and a `disabledToolsets` edit each do that once and
+  then hold. The block is NOT a fixed size — it is whatever the agent's
+  `enabledTools` serializes to; read `round start { tools }` and
+  `round stats { promptTokens }` from the harness log, never assume a figure.
+- **`modelId` is identity-by-config**: `sha256(type:src:sortedConfig)[:16]`. ANY
+  `modelConfig` field change — including `verbosity` from `QVAC_LLM_VERBOSITY` —
+  is a new `modelId`, a new cache directory, and a cold prime for every chat.
+  Debug the cache with `QVAC_HARNESS_LOG`/`xxd`, never by raising addon
+  verbosity. The system prompt is NOT in `modelId` (it is in `configHash`, the
+  file name): a prompt edit cold-primes one chat, a config edit cold-primes all.
+- **The addon compacts reasoning out of the KV itself.**
+  `remove_thinking_from_context` defaults to `true` (addon 0.33.0); since 0.48 it
+  rewinds to the block boundary and re-decodes what it keeps. `cacheTokens`
+  after a turn excludes thinking, so nothing above has to strip it.
+- **`ContextOverflowError` carries sizes** (0.19): `requiredTokens`, `ctxSize`,
+  `cachedTokens` on the warm guard, and `promptTokens` only when the guard
+  counted tokens. The harness matches the error by `name` (`CONTEXT_OVERFLOW`)
+  and reads none of them.
+
+## Before proposing caller-side eviction
+
+Ask whether the SDK cache would already handle it. The answer is yes for
+ordinary history growth; the cases that genuinely need handling above the SDK
+are a message (or tool result) larger than `ctx_size`, plus the cross-device
+cold start. Anything else is re-implementing the cache badly.
+
+**Compaction is the one sanctioned exception, and it already exists in
+`@qvac/core` — do not build a second one here.** It evicts from the prompt,
+never from the KV; it uses the SDK's own `cacheTokens` rather than token math;
+and it invalidates the chat key when a fold lands. The floor is
+`COMPACTION_MIN_CTX_SIZE` (4,096): below it a fold cannot pay for the ~420-token
+prefix it shares the window with, so those chats stay on the ladder here.
+
+## Debugging
+
+- `round stats { round, wallMs, TTFT, TPS, cacheTokens, promptTokens }` and
+  `round start { round, turns, tools }` — the per-round `hlog` in
+  [lib/capabilities/completion.ts](../../../lib/capabilities/completion.ts).
+  `cacheTokens` dropping back to system-prompt size mid-chat = a re-prime.
+  `turns` shrinking across an overflow with an identical outcome = an inert
+  ladder.
+- SDK `logMessagesToAddon` tags: `PROMPT_SEND` / `CACHE_INIT` / `NO_CACHE`. A
+  `CACHE_INIT` mid-chat is a re-prime.
+- No addon line reports eviction any more: `discarded N tokens`,
+  `[ContextSlider]` and `runtimeStats().contextSlides` left with sliding in
+  addon 0.48. A log that shows them is an old build.
+- Cache files: `{kvCacheDir}/{cacheKey}/{modelId}/{configHash}.bin`. Two files
+  under one chat key means `configHash` changed — a volatile system prompt costs
+  one cold prime per turn.
+
+## Versions — check these first
+
+**This behaviour is version-specific and has changed before.** Start every task
+here:
+
+```bash
+grep '"@qvac/sdk"' package.json
+grep '"version"' node_modules/@qvac/inference/package.json node_modules/@qvac/llm-llamacpp/package.json
+```
+
+This repo pins **`@qvac/sdk` 0.19.0** → **`@qvac/inference` 0.19.0** →
+**`@qvac/llm-llamacpp` 0.49.1**. Since 0.19 `@qvac/sdk` is a thin re-export over
+`@qvac/inference`, and the `#sdk` import seam resolves to `@qvac/inference`
+in-process on Bare — so the cache code that runs is
+`node_modules/@qvac/inference/dist/plugins/builtin/llamacpp-completion/ops/`
+(`completion-stream.js`, `kv-cache-session.js`, `context-overflow.js`), not
+anything under `@qvac/sdk/dist`. If the shipped numbers move past these, re-read
+before acting.
+
+Whenever you re-verify something, update the Versions section in
+[docs/kvcache-reference.md](../../../docs/kvcache-reference.md) in the same
+commit.

package/.claude/skills/pr-create/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: pr-create
+description: Write the title, body and commits for a pull request in @qvac/harness, and decide the conventional-commit type for a change — `fix` is reserved for user-facing defects in a released version. Use when opening a PR here, splitting work into a stack, or choosing between `fix` and `chore`.
+---
+
+# PR creation
+
+`@qvac/harness` is a published package. The log is the only durable record of intent,
+and for this repo it is also the changelog a consumer reads before upgrading.
+
+## Title
+
+```
+type(scope): subject
+```
+
+Imperative, lowercase after the colon, no trailing period. Scope optional, and
+only when it narrows something real. What and why, not how.
+
+```
+feat: publish the sidecar entry, so spawning it needs no bundle
+fix(publish): repoint dynamic imports at dist-lib too
+refactor: own the schema codegen tooling
+chore: regenerate the schema
+```
+
+There is no ticket prefix here, and no title validator in CI. That is not
+licence to be loose: nothing will catch a bad title but a reviewer.
+
+## Types
+
+```
+build  chore  ci  docs  style  refactor  perf  test  fix  feat
+```
+
+**`fix` is reserved for a defect a consumer of a released version could hit.**
+It is the line someone reads to decide whether to upgrade, so it claims real
+breakage in something already published.
+
+| The change | Type |
+| --- | --- |
+| Breaks a consumer on a published version | `fix` |
+| Repairs code that has never shipped (same release cycle) | `chore` |
+| Repairs the build, the bundle, or what lands in the tarball | `build` or `fix` if a published artifact was wrong |
+| Repairs CI, a workflow, an action pin | `ci` |
+| Repairs or adds a test | `test` |
+| Repairs a lint/type error | `chore` |
+| Pure move or rename, no behaviour change | `refactor` |
+| New capability, new export, new flag | `feat` |
+| README, comments, docs | `docs` |
+
+When a repair is on unreleased code, check the last release tag: if the bug was
+never in a published version, it is `chore`, not `fix`.
+
+Never relabel a real defect as `chore` to make the log quieter, and never
+inflate a cleanup into `fix` to make it look urgent.
+
+## Scopes
+
+Optional, and taken from what the diff actually touches — `lib`, `worker`, `schema`, `spec`, `scripts`, `test`, `ci`, `publish`, or a capability name (`completion`, `tools`, `models`).
+A scope that restates the type (`fix(fix)`) or names the whole repo adds
+nothing; leave it off.
+
+## Small PRs, stacked
+
+A PR is read by a human, so it has to fit in one head. Default to one concern.
+When a change decomposes into dependent steps, do not grow one PR to fit them —
+stack them, so each step is reviewable alone and lands in order.
+
+- A large refactor belongs on a `refactor/...` branch with `refactor:` commits.
+- **Refactor commits never live inside a non-refactor branch.** A `feat/` branch
+  that also reshuffles unrelated code is two PRs. Behaviour changes and pure
+  moves are reviewed differently, and mixing them hides both.
+- A pure rename or move lands *before* the change that depends on it, as its own
+  commit or its own PR in the stack.
+
+Branch names must never contain `codex`, `cursor`, or `claude` (case
+insensitive). Use a neutral name before committing or pushing.
+
+## Body
+
+No template is enforced. Use these four headings and drop any that would be
+empty — an absent section says more than a section saying "n/a".
+
+```markdown
+## What
+
+One paragraph. The change, in the reviewer's terms.
+
+## Why
+
+The problem this solves, or the decision it implements. Link the issue,
+PR, or upstream change that forced it.
+
+## How
+
+Only the parts a reader would not infer from the diff: the seam that moved,
+the invariant being preserved, the thing that looks wrong but isn't.
+
+## Testing
+
+What you ran, and what it proved. ``bun run test` (node, bare and addon lanes)` at minimum.
+Say plainly when something could not be tested locally and why.
+```
+
+For a **breaking change**, say so in the body under its own `## Breaking`
+heading, with the migration a consumer has to perform. Published package —
+this is the only warning they get.
+
+## Before opening
+
+1. Check the branch is not `main` and the name is neutral.
+2. `git log --oneline main..HEAD` — every commit is a conventional commit, and
+   each one is a change you would defend on its own.
+3. ``bun run lint`` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
+   red PR wastes a reviewer's round trip.
+4. Rebase on `main` rather than merging it in. A merge commit in the branch
+   makes the diff unreadable.
+5. Open as a **draft** unless you are asking for review right now.
+
+```bash
+gh pr create --repo tetherto/qvac-harness --draft --title "type(scope): subject" --body-file <path>
+```
+
+Never push to `main`, never force-push a branch someone else is reviewing, and
+never open a PR that carries commits you did not write without saying so.
+
+## Version bumps
+
+Release PRs in this repo are titled by version alone (`0.2.4 (#32)`,
+`release/0.1.4 (#40)`). They carry the version bump and nothing else — do not
+fold a bump into a feature PR, and do not fold a feature into a bump.
+
+## Sibling skills
+
+- Reviewing a PR or a local diff → **pr-review**.
+- How the code itself should be shaped → **js-house-style**.

package/.claude/skills/pr-review/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: pr-review
+description: Deep-dive review of a pull request in @qvac/harness, or of local uncommitted/branch changes when invoked with `local`. Checks CI, the commit type and title, code quality against the house style, contract and API mismatches, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
+---
+
+# PR review
+
+Reviews changes in `@qvac/harness`. Two modes.
+
+- **PR mode** (a PR number or URL) — a short overview in chat, then a **pending**
+  GitHub review of per-file inline comments. The pending review is created only
+  after the user confirms the exact set of comments. **Never submit the review
+  event** (`COMMENT`, `REQUEST_CHANGES`, `APPROVE`) — that is the user's call,
+  from the GitHub UI.
+- **Local mode** (`local`, or "review my changes") — the overview in chat only.
+  Posts nothing, anywhere.
+
+## Gather
+
+PR mode:
+
+```bash
+gh pr view <num> --repo tetherto/qvac-harness \
+  --json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable
+gh pr diff <num> --repo tetherto/qvac-harness --patch > /tmp/pr-<num>.patch
+```
+
+Read the patch from the file with Read/Grep rather than re-running `gh` — it is
+the same bytes every time and the file is greppable.
+
+Local mode:
+
+```bash
+git diff --staged > /tmp/local-staged.patch
+git diff > /tmp/local-unstaged.patch
+git status --porcelain=v1
+git ls-files --others --exclude-standard    # untracked, easy to miss
+```
+
+For a branch rather than a working tree: `git diff main...HEAD` (three dots —
+the merge base, not the tip).
+
+## CI
+
+One workflow gates this repo: **Integrate** (`.github/workflows/ci.yml`), a
+single `Lint & Tests` job. `publish.yml` runs on release, not on PRs.
+
+Its steps are each a separate way to fail, and the last three catch what a
+local `bun run test` does not:
+
+| Step | Command | Fails when |
+| --- | --- | --- |
+| Lint | `bun run lint` | prettier, lunte or `tsc --noEmit` |
+| Schema is regenerated | `bun run build:schema` | `spec/` is dirty after codegen — someone hand-edited it, or forgot to commit the regeneration |
+| Tests | `bun run test` | the node, bare and addon lanes |
+| Library surface compiles | `bun run build:lib` | the compiled export surface breaks |
+| Sidecar bundle builds | `bun run build:bundle` | the stowed bundle no longer assembles — a new bare import, or a missing addon external |
+
+A PR that touches `schema/` and leaves `spec/` stale is the most common red
+here, and it looks nothing like a test failure.
+
+```bash
+gh pr checks <num> --repo tetherto/qvac-harness
+gh run view --repo tetherto/qvac-harness --log-failed --job <id> > /tmp/pr-<num>-<id>.log
+```
+
+A red `Integrate` is a blocking finding on its own. Read the failing job's log
+before writing a single line of review — half of what looks like a design
+problem is a lint rule.
+
+## What to check, in order
+
+Stop at the first tier that produces findings worth the author's time; a review
+that lists twelve nits under a broken contract has buried the real thing.
+
+**1. Correctness.** Does it do what the title claims? Trace the changed path
+end to end, including the error path. Look for: a promise not awaited, a
+listener never removed, a resource opened on one path and closed on another, an
+error swallowed into a default.
+
+**2. Contract and API.** This is a published package, so an exported signature
+is a promise to a consumer.
+
+- Anything added to or changed in the export map, `index.ts`, `types/`, or
+  `package.json#exports` — is it intentional, and is it a breaking change?
+- `schema/` or `spec/` changes: is the wire format still compatible, and was the
+  baseline regenerated (`bun run build:schema`) rather than hand-edited?
+- Does the change match its own type declarations, and do callers in this repo
+  still typecheck?
+
+**3. House style.** Run the changed files against **js-house-style** — that
+document, not your own taste. Layering, composition on primitives, module size
+and shape, no defensive programming, comment density.
+
+**4. Tests.** A behaviour change with no test is a finding. Name the missing
+case rather than asking for "more tests": the tests live under `test/`, run on
+both the node and bare lanes, and a fix without a regression guard will come
+back.
+
+**5. Commit type and title.** Per **pr-create**: is this really a `fix` (a
+defect a consumer of a released version could hit), or is it `chore` on code
+that never shipped? Is the title imperative and specific? Does the branch name
+avoid `codex` / `cursor` / `claude`?
+
+**6. Scope.** Does the PR do one thing? A behaviour change mixed with an
+unrelated rename is two PRs — say so, and say which commit to split out.
+
+## Write the findings
+
+Each finding: the file and line, what breaks, and the concrete scenario that
+breaks it. No finding without a failure mode you can state.
+
+Drop anything you cannot defend as changing the code, the reviewer's decision,
+or a consumer's experience. Style opinions the house style does not back are
+noise. Say so plainly when the diff is clean — "no blocking findings" is a
+complete review.
+
+Distinguish clearly:
+
+- **Blocking** — wrong behaviour, a broken contract, a missing test for a fix.
+- **Non-blocking** — a simplification, a naming improvement, a follow-up.
+- **Question** — you could not tell from the diff, and the author can.
+
+## Posting (PR mode only)
+
+1. Print every proposed comment in chat first: file, line, body.
+2. Ask the user to confirm the exact set. Wait for a clear yes.
+3. Create the review as **PENDING**, with no event:
+
+```bash
+gh api repos/tetherto/qvac-harness/pulls/<num>/reviews \
+  --method POST --input /tmp/review.json
+```
+
+where `review.json` has `commit_id` (the `headRefOid` you fetched) and a
+`comments` array of `{path, line, side, body}`, and **no `event` field**. A body
+with `event` submits the review; leaving it out is what makes it pending.
+
+4. Hand the user the link and stop:
+   `https://github.com/tetherto/qvac-harness/pull/<num>#pullrequestreview-<id>`
+
+If a line is not in the diff, GitHub rejects the comment. Anchor to a line the
+patch actually touches, or raise it in the chat overview instead.
+
+## Sibling skills
+
+- Writing the PR being reviewed → **pr-create**.
+- The rules tier 3 reviews against → **js-house-style**.

package/CLAUDE.md

@@ -0,0 +1,36 @@
+# @qvac/harness
+
+The QV.AC inference engine: `generate(context)` over the QVAC SDK, plus the tool
+runtime skills execute in. **Inference in, events out** — it knows nothing about
+the app, hyperdb or sync. It runs as a supervised child process (or a Bare thread
+on mobile) that a host spawns and talks to over hrpc.
+
+Runs on both Bare and Node. Anything that only works on one is a bug.
+
+## Durable invariants
+
+- **The published package spawns; it does not import.** The tarball ships the
+  prebuilt bundle and its runtime content, and its export map deliberately points
+  at files it omits. That map is not broken — do not "fix" it.
+- **`spec/` is generated** by `bun run build:schema`. Never hand-edit it; CI fails
+  when it is dirty after regeneration.
+- **Dependency `overrides` pin the resolutions the engine is validated against.**
+  Keep them aligned with the direct specs — npm refuses a mismatch on publish.
+- **The cache is the SDK's.** Do not add caller-side history eviction or
+  chars-per-token estimation.
+
+## Working here
+
+- `bun run lint` (prettier + lunte + tsc) and `bun run test` (node, bare and
+  addon lanes) before considering a change done.
+- Tests live in `test/` and run under brittle. A non-trivial change ships tests.
+
+## Always
+
+- **Comment only what the code cannot say.** Why, not what. One or two lines,
+  never more. Most code needs none — do not narrate it.
+- **Commits read as if a human wrote them.** No `Co-Authored-By` trailer and no
+  AI or agent attribution, in a commit message or a PR.
+- **Branch from `main`, and open the PR against `main`.** The one exception is a
+  stacked PR, which branches from the PR below it and targets that branch.
+- **Branch names never contain `codex`, `cursor` or `claude`**, in any case.