@qvac/harness 0.2.5 → 0.2.7

package/dist/prebuilds-manifest.json

@@ -272,14 +272,6 @@
       "win32-arm64",
       "win32-x64"
     ],
-    "bare-tty/node_modules/bare-signals": [
-      "darwin-arm64",
-      "darwin-x64",
-      "linux-arm64",
-      "linux-x64",
-      "win32-arm64",
-      "win32-x64"
-    ],
     "bare-tty": [
       "darwin-arm64",
       "darwin-x64",

package/dist-lib/index.d.ts

@@ -82,6 +82,7 @@ export interface HarnessOptions {
     transcriptionDevice?: 'cpu' | 'gpu';
     credentialStore?: CredentialStoreFn;
     platform?: string;
+    completionModelCap?: number;
 }
 export interface CompletionContext {
     model: string;
@@ -133,6 +134,7 @@ export declare class Harness extends ReadyResource {
     private readonly _kvCacheV?;
     private readonly _transcriptionDevice?;
     private readonly _gpuStats?;
+    private readonly _completionModelCap;
     private _allSkills;
     private _credentialStore?;
     private _credentials;
@@ -145,7 +147,7 @@ export declare class Harness extends ReadyResource {
     private _capability;
     private _capabilityInflight;
     private readonly _modelFaults;
-    constructor({ tools, sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, credentialStore, platform, gpuStats }?: HarnessOptions);
+    constructor({ tools, sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats }?: HarnessOptions);
     _open(): Promise<void>;
     get suspended(): boolean;
     get skillNames(): string[];
@@ -238,6 +240,7 @@ export declare class Harness extends ReadyResource {
         signal?: BareAbortSignal;
     }): Promise<void>;
     completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }: CompletionContext): AsyncGenerator<CompletionEvent>;
+    private _makeRoomForCompletion;
     private _evictWedgedModel;
     private _evictAfterLeases;
 }

package/dist-lib/index.js

@@ -17,7 +17,7 @@ import { AbortedError, raceAbort } from "./lib/helpers/race-abort.js";
 import { audioGenDownloadMetadata, customProjectionMap, defaultProjectionMap, defaultTtsFor, defaultVoiceModel, diffusionDownloadMetadata, infraModelsFor, modelNameToCapabilityProfile, musicModelSet, setCustomModels } from "./lib/models/model-catalog.js";
 import { createModelStatusCache, invalidateModelStatusCache, listModels } from "./lib/models/model-list.js";
 import { deleteModelFiles, summarizeDelete } from "./lib/models/model-delete.js";
-import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, evictAllWithin, evictIdle, evictModelWithin, isResident, leaseCount, loadedModels, modelKey, releaseModel, resolveLoadOptions, progressState } from "./lib/models/model-pool.js";
+import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, awaitModelCapacity, evictIdle, evictModelWithin, isResident, leaseCount, loadedModels, modelKey, releaseModel, resolveLoadOptions, progressState } from "./lib/models/model-pool.js";
 import { resolveMainGpu } from "./lib/models/gpu-selection.js";
 import { openclCacheDir } from "./lib/models/opencl-cache.js";
 import { assertEmbedDevice, createEmbedConfig } from "./lib/models/embed-config.js";
@@ -68,6 +68,9 @@ const TRANSCRIPTION_MODEL_LABEL = 'transcription model';
 const DIFFUSION_EVICT_WAIT_MS = 15_000;
 const MUSIC_EVICT_WAIT_MS = 15_000;
 const WEDGED_EVICT_WAIT_MS = 10_000;
+const MODEL_ROOM_WAIT_MS = 300_000;
+const WARM_ROOM_WAIT_MS = 2_000;
+const DEFAULT_COMPLETION_MODEL_CAP = 1;
 const WEDGED_EVICT_LEASED_MS = 120_000;
 const TTS_MODEL_CONFIG = {
     ttsEngine: 'supertonic',
@@ -104,6 +107,7 @@ export class Harness extends ReadyResource {
     _kvCacheV;
     _transcriptionDevice;
     _gpuStats;
+    _completionModelCap;
     _allSkills;
     _credentialStore;
     _credentials = new Map();
@@ -116,7 +120,7 @@ export class Harness extends ReadyResource {
     _capability = null;
     _capabilityInflight = null;
     _modelFaults = new Map();
-    constructor({ tools = [], sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, credentialStore, platform, gpuStats } = {}) {
+    constructor({ tools = [], sdkLoader, skillsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats } = {}) {
         super();
         this._sdk = sdkLoader ?? createSdkLoader();
         this._llmDevice = llmDevice;
@@ -126,6 +130,7 @@ export class Harness extends ReadyResource {
         this._kvCacheK = kvCacheK;
         this._kvCacheV = kvCacheV;
         this._transcriptionDevice = transcriptionDevice;
+        this._completionModelCap = completionModelCap ?? DEFAULT_COMPLETION_MODEL_CAP;
         const embedConfig = createEmbedConfig({
             device: embedDevice,
             gpuLayers: embedGpuLayers,
@@ -168,7 +173,7 @@ export class Harness extends ReadyResource {
                 onBeforeLoad: async (signal) => {
                     if (this._models.destroyed)
                         return;
-                    const evicted = await evictAllWithin(this._models, DIFFUSION_EVICT_WAIT_MS, undefined, signal);
+                    const evicted = await awaitModelCapacity(this._models, 1, DIFFUSION_EVICT_WAIT_MS, undefined, signal);
                     if (signal?.aborted)
                         throw new AbortedError();
                     if (!evicted) {
@@ -187,7 +192,7 @@ export class Harness extends ReadyResource {
                 onBeforeLoad: async (signal) => {
                     if (this._models.destroyed)
                         return;
-                    const evicted = await evictAllWithin(this._models, MUSIC_EVICT_WAIT_MS, undefined, signal);
+                    const evicted = await awaitModelCapacity(this._models, 1, MUSIC_EVICT_WAIT_MS, undefined, signal);
                     if (signal?.aborted)
                         throw new AbortedError();
                     if (!evicted) {
@@ -927,7 +932,8 @@ export class Harness extends ReadyResource {
         const pool = this._models;
         hlog('warm model', { model, resident: isResident(pool, key) });
         if (!isResident(pool, key)) {
-            await evictIdle(pool);
+            if (!(await this._makeRoomForCompletion(signal, WARM_ROOM_WAIT_MS)))
+                return;
             await this._imageRuntime?.unloadIdle().catch(noop);
         }
         try {
@@ -953,13 +959,13 @@ export class Harness extends ReadyResource {
         const resident = isResident(pool, key);
         hlog('completion start', { model, resident, projection: Boolean(projectionModel) });
         if (!resident) {
-            await evictIdle(pool);
+            await this._makeRoomForCompletion(signal);
             await this._imageRuntime?.unloadIdle().catch(noop);
             await this._musicRuntime?.unloadIdle().catch(noop);
         }
         const acquireRound = async () => {
             if (!isResident(pool, key)) {
-                await evictIdle(pool);
+                await this._makeRoomForCompletion(signal);
                 await this._imageRuntime?.unloadIdle().catch(noop);
                 await this._musicRuntime?.unloadIdle().catch(noop);
             }
@@ -1052,6 +1058,16 @@ export class Harness extends ReadyResource {
             void this._musicRuntime?.unloadIdle().catch(noop);
         }
     }
+    async _makeRoomForCompletion(signal, deadlineMs = MODEL_ROOM_WAIT_MS) {
+        const roomed = await awaitModelCapacity(this._models, this._completionModelCap, deadlineMs, 250, signal);
+        if (!roomed) {
+            hlog('model room wait gave up', {
+                cap: this._completionModelCap,
+                loaded: loadedModels(this._models).length
+            });
+        }
+        return roomed;
+    }
     async _evictWedgedModel(model, key) {
         const faults = (this._modelFaults.get(model) ?? 0) + 1;
         this._modelFaults.set(model, faults);

package/dist-lib/lib/docx/index.d.ts

@@ -0,0 +1,5 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export { closePythonWorker as closeDocxWorker } from '../tools/exec/adapters/python/worker/client.ts';
+export declare function extractDocxText(bytes: Uint8Array, fileName: string, options?: {
+    readonly signal?: AbortSignal;
+}): Promise<string>;

package/dist-lib/lib/docx/index.js

@@ -0,0 +1,49 @@
+import b4a from 'b4a';
+import fs from 'fs';
+import { runPython } from "../tools/exec/adapters/python/pyodide.js";
+import { planVendoredInstall, vendoredManifest, wheelsDir } from "../tools/exec/adapters/python/wheels.js";
+export { closePythonWorker as closeDocxWorker } from "../tools/exec/adapters/python/worker/client.js";
+const MAX_OFFICE_BYTES = 20 * 1024 * 1024;
+const PACKAGES = ['python-docx==1.2.0'];
+const EXTRACT = `from docx import Document
+from docx.text.paragraph import Paragraph
+from pathlib import Path
+
+def text(container):
+    for block in container.iter_inner_content():
+        if isinstance(block, Paragraph):
+            if block.text.strip():
+                yield block.text
+        else:
+            for row in block.rows:
+                yield " | ".join(" ".join(text(cell)) for cell in row.cells)
+
+Path("extracted.txt").write_text("\\n".join(text(Document("input.docx"))), encoding="utf-8")
+`;
+export async function extractDocxText(bytes, fileName, options = {}) {
+    if (bytes.byteLength > MAX_OFFICE_BYTES) {
+        throw new Error(`document is too large to extract: ${bytes.byteLength} bytes, limit ${MAX_OFFICE_BYTES}`);
+    }
+    const dir = wheelsDir();
+    const manifest = vendoredManifest(dir);
+    const install = planVendoredInstall(PACKAGES, { dir, manifest });
+    if (!dir ||
+        !manifest ||
+        !install ||
+        !['micropip', ...install.packages].every((name) => Object.keys(manifest.files).some((file) => file.replaceAll('_', '-').startsWith(`${name}-`) && fs.existsSync(`${dir}/${file}`)))) {
+        throw new Error('bundled DOCX extraction packages are unavailable');
+    }
+    const result = await runPython(EXTRACT, {
+        packages: PACKAGES,
+        inputs: [{ path: 'input.docx', bytes }],
+        outputs: ['extracted.txt'],
+        signal: options.signal
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`${fileName}: ${result.stderr.trim()}`);
+    const output = result.files?.get('extracted.txt');
+    if (!output) {
+        throw new Error(result.rejected?.[0]?.reason ?? 'DOCX extraction produced no text file');
+    }
+    return b4a.toString(output, 'utf8');
+}

package/dist-lib/lib/models/model-pool.d.ts

@@ -72,7 +72,7 @@ export declare function loadedModels(pool: PoolLike): LoadedModel[];
 export declare function isResident(pool: PoolLike, key: string): boolean;
 export declare function leaseCount(pool: PoolLike, key: string): number;
 export declare function evictIdle(pool: PoolLike): Promise<void>;
-export declare function evictAllWithin(pool: PoolLike, deadlineMs: number, tickMs?: number, signal?: {
+export declare function awaitModelCapacity(pool: PoolLike, cap: number, deadlineMs: number, tickMs?: number, signal?: {
     aborted?: boolean;
 }): Promise<boolean>;
 export declare function evictModelWithin(pool: PoolLike, key: string, deadlineMs: number, tickMs?: number): Promise<boolean>;

package/dist-lib/lib/models/model-pool.js

@@ -103,7 +103,8 @@ export async function evictIdle(pool) {
         await pool.gc();
     }
 }
-export async function evictAllWithin(pool, deadlineMs, tickMs = 250, signal) {
+export async function awaitModelCapacity(pool, cap, deadlineMs, tickMs = 250, signal) {
+    const roomed = () => loadedModels(pool).length < cap;
     let done = false;
     let timer = null;
     const expired = new Promise((resolve) => {
@@ -114,7 +115,7 @@ export async function evictAllWithin(pool, deadlineMs, tickMs = 250, signal) {
     });
     const evicting = (async () => {
         await evictIdle(pool);
-        while (loadedModels(pool).length > 0) {
+        while (!roomed()) {
             if (done || signal?.aborted)
                 return false;
             await new Promise((resolve) => setTimeout(resolve, tickMs));

package/dist-lib/lib/spawn.d.ts

@@ -20,6 +20,7 @@ export interface HarnessLlmConfig {
     contextSize?: number;
     kvCacheK?: string;
     kvCacheV?: string;
+    completionModelCap?: number;
 }
 export interface HarnessChildOptions {
     runner: StowRunner;

package/dist-lib/lib/tools/exec/adapters/python/pyodide.js

@@ -99,6 +99,8 @@ export async function runPython(code, options = {}) {
     }
     await runLock.lock();
     try {
+        if (options.signal?.aborted)
+            throw new AbortedError();
         return await runPythonInWorker(spec, { timeoutMs, signal: options.signal });
     }
     finally {

package/dist-lib/lib/tools/exec/adapters/python/wheels.js

@@ -17,7 +17,8 @@ export function wheelsDir() {
     const fromHost = process.env.QVAC_PYTHON_WHEELS_DIR;
     if (fromHost)
         return fromHost;
-    const source = new URL('../../../../../wheels', import.meta.url);
+    const root = new URL('../../../../../', import.meta.url);
+    const source = new URL(root.pathname.endsWith('/dist-lib/') ? '../wheels' : 'wheels', root);
     if (source.href.includes('.bundle/'))
         return undefined;
     return fileURLToPath(source.href);

package/dist-lib/lib/tools/exec/adapters/python/worker/client.js

@@ -13,7 +13,7 @@ const SHUTDOWN_GRACE_MS = 3_000;
 let active = null;
 function workerEntry() {
     return (process.env.QVAC_PYODIDE_WORKER_ENTRY ??
-        fileURLToPath(new URL('./entry.ts', import.meta.url).href));
+        fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './entry.ts' : './entry.js', import.meta.url).href));
 }
 async function readMessage(link) {
     for (;;) {

package/dist-lib/schema/generate.d.ts

@@ -13,8 +13,12 @@ interface HRPCHandler {
 interface HRPCBuilderLike {
     handlers: ReadonlyArray<HRPCHandler>;
 }
+interface CallSiteOptions {
+    readonly optionalRequests?: ReadonlySet<string>;
+    readonly exportName?: string;
+}
 export declare function writeBind(builder: HRPCBuilderLike, outFile: string): void;
-export declare function writeClient(builder: HRPCBuilderLike, outFile: string, exportName?: string): void;
-export declare function writeCapabilities(builder: HRPCBuilderLike, outFile: string): void;
+export declare function writeClient(builder: HRPCBuilderLike, outFile: string, options?: CallSiteOptions | string): void;
+export declare function writeCapabilities(builder: HRPCBuilderLike, outFile: string, options?: CallSiteOptions): void;
 export declare function writeConfigTypes(outFile: string): void;
 export {};

package/dist-lib/schema/generate.js

@@ -13,6 +13,7 @@ function camel(name, prefix = '') {
     return prefix + cased.join('');
 }
 const HEADER = '// This file is autogenerated by schema/build.js\n// Do not edit manually.\n\n';
+const DEFAULT_OPTIONAL_REQUESTS = new Set(['@assistant/empty']);
 export function writeBind(builder, outFile) {
     let s = `${HEADER}import { pipeline, Readable } from "streamx";\n\nfunction noop() {}\n\nexport function bindApi(rpc, api) {\n`;
     for (const handler of builder.handlers) {
@@ -56,24 +57,28 @@ export function writeBind(builder, outFile) {
     s += '}\n';
     fs.writeFileSync(outFile, s);
 }
-export function writeClient(builder, outFile, exportName = 'engineClient') {
+export function writeClient(builder, outFile, options = {}) {
+    const callSite = typeof options === 'string' ? { exportName: options } : options;
+    const { optionalRequests = DEFAULT_OPTIONAL_REQUESTS, exportName = 'engineClient' } = callSite;
     let s = `${HEADER}function noop() {}\n\nfunction armed(stream) {\n  stream.on("error", noop);\n  return stream;\n}\n\nexport function ${exportName}(rpc) {\n  return {\n`;
     for (const handler of builder.handlers) {
         const method = camel(handler.name);
+        const input = optionalRequests.has(handler.request?.name ?? '') ? 'input ?? {}' : 'input';
         if (handler.request?.stream && handler.response?.stream) {
             s += `    ${method}: () => armed(rpc.${method}()),\n`;
         }
         else if (handler.response?.stream) {
-            s += `    ${method}: (input) => armed(rpc.${method}(input)),\n`;
+            s += `    ${method}: (input) => armed(rpc.${method}(${input})),\n`;
         }
         else {
-            s += `    ${method}: (input) => rpc.${method}(input),\n`;
+            s += `    ${method}: (input) => rpc.${method}(${input}),\n`;
         }
     }
     s += '  };\n}\n';
     fs.writeFileSync(outFile, s);
 }
-export function writeCapabilities(builder, outFile) {
+export function writeCapabilities(builder, outFile, options = {}) {
+    const { optionalRequests = DEFAULT_OPTIONAL_REQUESTS } = options;
     let s = HEADER;
     s += "import type * as T from './hyperschema/types.d.ts'\n\n";
     s +=
@@ -112,7 +117,7 @@ export function writeCapabilities(builder, outFile) {
         const method = camel(handler.name);
         const req = `T.${tsName(handler.request.name)}`;
         const res = `T.${tsName(handler.response.name)}`;
-        const input = handler.request.name === '@assistant/empty' ? `input?: ${req}` : `input: ${req}`;
+        const input = optionalRequests.has(handler.request.name) ? `input?: ${req}` : `input: ${req}`;
         if (handler.request?.stream && handler.response?.stream) {
             client += `  ${method}(): UploadStream<${req}, ${res}>\n`;
             server += `  ${method}(stream: AsyncIterable<${req}> | HandlerFrames<${req}>): AsyncIterable<${res}>\n`;

package/docs/decisions/2026-05-29-kvcache-tool-turns.md

@@ -0,0 +1,75 @@
+---
+id: ADR-2026-05-29-kvcache-tool-turns
+status: superseded
+introduced_by: PR-228
+supersedes: []
+superseded_by: [ADR-2026-06-02-kvcache-tool-turns-reenabled]
+---
+
+# KV-cache session is disabled for tool-using completions
+
+> **Superseded** by
+> [ADR-2026-06-02-kvcache-tool-turns-reenabled](./2026-06-02-kvcache-tool-turns-reenabled.md):
+> the cache is re-enabled for tool turns now that models load with
+> `toolsMode: "dynamic"` (the SDK's DYNAMIC path is coherent, including across
+> reload). Kept for history.
+
+## Decision
+
+The `@qvac/sdk` session prompt cache (`completion({ kvCache })`) is passed
+**only for tool-free completions** — `kvCache` is set only when
+`tools.length === 0`. Agentic / tool-using turns always run without the session
+cache.
+
+## Context
+
+The SDK session cache has two paths (see
+`@qvac/sdk → server/bare/plugins/llamacpp-completion/ops/completion-stream.ts` in the SDK):
+
+- **STATIC** (no `tools`): on a cache hit it sends `history.slice(savedCount)`
+  and self-heals a stale boundary by re-sending the full history. Robust against
+  our reconstructed history.
+- **DYNAMIC** (`tools` present): on a cache hit it sends only a role-based
+  _fragment_ of the history and trusts the SDK's own tool-chain flow to have
+  anchored the rest of the cache.
+
+Our agentic loop builds (and on reload reconstructs from a persisted transcript)
+the full history its own way. That does not satisfy the DYNAMIC path's
+assumptions, so on a tool-cache hit the model receives an incoherent prompt and
+emits `<tool_call>` markup as plain text instead of a parseable tool call —
+silently breaking tool calling (no parse, no approval, no execution). Tools are
+text-parsed (`toolCalling: "textParse"`), so a corrupted prompt degrades to a
+plain assistant message rather than erroring.
+
+## Alternatives Considered
+
+- **Always-on per-chat `kvCache`** (the state that introduced the regression):
+  breaks tool calling as above.
+- **Auto-cache (`kvCache: true`)**: tool-call turns are never cached, and a
+  verbatim `cacheableAssistantContent` echo is required for a hit —
+  incompatible with our thinking-stripped reconstruction.
+- **Conform to the SDK's tool-chain contract** (collapse consecutive messages +
+  `deleteCache` on divergence, like the legacy desktop worker): viable but a
+  separate project, tracked in `.ai/cursor/plans/kvcache-tool-turn-reuse.md`.
+
+## Consequences
+
+- Tool turns re-prefill the full history each call (no session-cache reuse).
+  Tool calling stays correct; this is the prior known-good behavior.
+- Tool-free turns (plain chat / title / summary) still benefit from the STATIC
+  cache path.
+- Regression guards are GPU-free and mock-based:
+  `qvac-app → core/src/services/message/agentic-completion.test.ts` (argument-contract:
+  never send `kvCache` with `tools`) and the spec-fake
+  `qvac-app → core/src/services/message/__fixtures__/fake-completion-sdk.ts` (reproduces the
+  cache-hit tool-parse failure).
+- Revisit if the SDK adds a "send full history, you slice it" mode for tools, or
+  when the conformance project lands.
+
+## When Agents Should Read This
+
+Read this before changing how `kvCache` is passed to `sdk.completion`, the
+agentic loop's history construction, or transcript reconstruction —
+`qvac-app → core/src/services/message/agentic-completion.ts`,
+`qvac-app → core/src/services/message/agentic-loop.ts`,
+`qvac-app → core/src/services/common/transcript.ts`.

package/docs/decisions/2026-06-02-kvcache-tool-turns-reenabled.md

@@ -0,0 +1,127 @@
+---
+id: ADR-2026-06-02-kvcache-tool-turns-reenabled
+status: superseded
+introduced_by: PR-QVAC-19770
+supersedes: [ADR-2026-05-29-kvcache-tool-turns]
+superseded_by: [ADR-2026-08-20-kvcache-static-placement]
+---
+
+# KV-cache session is re-enabled for tool-using completions
+
+> **Superseded** by
+> [ADR-2026-08-20-kvcache-static-placement](./2026-08-20-kvcache-static-placement.md):
+> the half of this record that still holds is that `kvCache: 'chat-<id>'` rides
+> every completion. The dynamic-mode half was built on a false premise — the
+> addon's compact-tools anchoring never ran on any shipped model (its arch gate
+> is exact `qwen3`; ours are `qwen35`/`qwen36`), so the coherence this record
+> credits to dynamic mode was never exercised, and the "static never surfaced
+> the tool-call format" claim did not survive re-testing. core-v2 loads static
+> with no sliding window since 2026-08-20; mechanics in
+> `docs/kvcache-reference.md`. The `QVAC_PROMPT_CACHE` kill-switch and
+> `deleteChatPromptCache` described below were core-v1 machinery and do not
+> exist in the current runtime.
+
+## Decision
+
+The `@qvac/sdk` session prompt cache (`completion({ kvCache: "chat-<id>" })`) is
+passed for **all** completions with a chatId — tool-using and tool-free alike —
+gated only by the `QVAC_PROMPT_CACHE` kill-switch. This reverses
+ADR-2026-05-29, which disabled the cache whenever tools were present.
+
+## Context
+
+The prior decision disabled tool-turn caching because the SDK's DYNAMIC cache
+path broke tool-call parsing: it ships a role-based history fragment and trusts
+the addon's tool-chain anchoring, which our reconstructed history did not
+satisfy → `<tool_call>` markup leaked as text. Two things changed:
+
+- Models loaded with `modelConfig.toolsMode: "dynamic"` (QVAC-19660). In
+  dynamic mode the addon anchors tools per-turn (compact-tools), excludes the
+  tool set from the cache config hash, and the fragment slicing keeps
+  multi-round tool turns coherent — including across a model evict/reload.
+  **No longer true as of `@qvac/sdk` 0.18 (QVAC-23936):** the key was removed
+  and the parser rejects it, so static is the only placement. Dynamic was in
+  any case a silent no-op on every arch we ship — the addon gates
+  `tools_compact` on exact-arch `qwen3` while our catalog is `qwen35`/`qwen36` —
+  and the SDK still sliced as-if-dynamic, which made the cache the chat's
+  _memory_ rather than an accelerator: after any cache reset it sent only the
+  last exchange. Under static placement the tool block sits in the addon's
+  protected prefix instead, and 0.18 keeps it out of the primed prefix
+  (QVAC-23251) so the qwen3.5 template no longer raises 'No user query found in
+  messages.'
+- An SDK e2e guard (`kv-cache-tools-dynamic-reuse`, plus a qwen35-dialect
+  variant) verifies a custom-key multi-round tool chain reuses the on-disk cache
+  (`cacheTokens > 0`) and keeps tool calls parseable across an evict/reload.
+
+With the DYNAMIC path proven coherent across reload, the heavyweight
+"reconstruction invalidation / byte-identical history" work the prior ADR
+deferred is unnecessary; divergence is handled with targeted invalidation.
+
+## Consequences
+
+- **Do not pass `toolsMode` at model load.** SDK 0.18 removed the key and its
+  parser rejects an unrecognised one, so passing it fails the load outright and
+  the app parks on the splash. Static placement is the default and the only mode.
+- Dropping a key from `modelConfig` re-keys `modelId`, which is identity-by-config,
+  so expect one cold prime per chat on the first run after such a change.
+- Tool turns reuse the session KV cache: lower TTFT/prefill on multi-round tool
+  turns and follow-ups (manually: round-2 TTFT ~1.1s → ~0.3s; cacheTokens grows
+  monotonically across a conversation).
+- `QVAC_PROMPT_CACHE` (default on; `0`/`false`/`off`) disables all
+  prompt caching as a kill-switch.
+- The per-chat cache is explicitly invalidated on chat delete and agent delete
+  (which cascades to its chats) via `deleteChatPromptCache`, plus a defensive
+  drop on retry (see below). Edit / branch / truncate flows do not exist yet and
+  need no hook.
+- **Why stop / failed / new-message-after-failure need no invalidation.** The
+  cache only ever holds _successful_ turns: the SDK rolls back uncommitted turns
+  on abort (the custom-key path commits only when not aborted and tokens were
+  produced), and failed / canceled / not_delivered replies are excluded from
+  model-visible history (`isModelVisibleMessage`, `qvac-app → core/src/services/common/history.ts`).
+  So a stopped or failed turn leaves neither a committed cache entry nor a
+  visible history row — the reconstructed history and the cached prefix stay
+  aligned, and the next turn (new message or retry) does not slice against a
+  stale prefix. The SDK's own `kv-cache-cancel-then-new-prompt` e2e covers this
+  cancel-then-continue coherence. The **retry** `deleteChatPromptCache` is
+  therefore belt-and-suspenders, not load-bearing: it costs one re-prime on a
+  rare, user-initiated path and removes any dependence on the rollback timing.
+- **Mobile scope.** Mobile now runs the same assistant and harness completion path
+  inside its supervised Bare worklets, so the per-chat cache key reaches the SDK
+  without the retired worker-to-host SDK bridge.
+- `chatPromptCacheKey` is the single source of truth for the `chat-<id>` key
+  shared by the completion path and the invalidation callers.
+- Known SDK limitation: on a multimodal (M-RoPE, `n_pos_per_embd > 1`) model such
+  as Qwen3.5, the SDK's KV sliding-window position shift (`seq_add`/`seq_div` via
+  `trySlidePrefill`) GGML_ASSERT-crashes the worker when the context fills. A
+  standalone SDK repro confirmed this is **independent of `toolsMode` (static and
+  dynamic both crash) and of whether tools are passed**, and is not caused by the
+  prompt cache — it is the sliding window itself, unsupported for multi-pos
+  models. Interim mitigation (separate from the kill-switch): we temporarily
+  stopped setting `n_discarded` at model load so on overflow the SDK took the
+  catchable `CONTEXT_OVERFLOW` path instead of the crashing slide.
+  **Resolved (2026-06-23):** `@qvac/sdk` 0.13.5 (llm-llamacpp 0.24.0) ships
+  M-RoPE/iM-RoPE sliding-context support, so `n_discarded` is set again in
+  `@qvac/sdk → model/model-load-config.ts` and the workbench no longer trims history. See
+  [`2026-06-23-append-only-history.md`](./2026-06-23-append-only-history.md).
+- Regression guards updated: the contract test now asserts `kvCache` IS sent
+  with tools; the spec-fake models dynamic mode (healthy on a tools cache hit);
+  invalidation hooks are covered.
+- **The in-repo suite cannot prove real dynamic-mode coherence.** The spec-fake
+  (`@qvac/sdk → __fixtures__/fake-completion-sdk.ts`) is parameterized to treat dynamic mode
+  as healthy, so the in-repo tests guard against regressing the model load back
+  to static mode and against dropping the `kvCache` key — but they do not prove
+  the SDK's real DYNAMIC path stays coherent against our reconstructed history.
+  That proof lives in the out-of-repo SDK e2e (`kv-cache-tools-dynamic-reuse`
+  and its qwen35 variant), which this repo's CI cannot run.
+
+## When Agents Should Read This
+
+Read this before changing how `kvCache` is passed to `sdk.completion`,
+`toolsMode` at model load, the agentic loop's history construction, transcript
+reconstruction, or the cache invalidation hooks —
+`qvac-app → core/src/services/message/agentic-completion.ts`,
+`qvac-app → core/src/services/model/service.ts`,
+`qvac-app → core/src/services/execution/service.ts`,
+`qvac-app → core/src/services/api/domain-apis.ts`,
+`@qvac/core → lib/assistant.ts`, and
+`lib/capabilities/completion.ts`.