QVAC-22567 feat[bc]: remove SDK dynamic tools mode (toolsMode)

[iancris]

🎯 What problem does it solve?

Companion to #3373 (addon-side removal). The SDK's dynamic tools mode (toolsMode: 'dynamic') maps to the llm-llamacpp tools_compact feature, which only works for Qwen3 and relies on sliding-context anchor bookkeeping that does not carry over to newer LLM models. This PR removes the SDK-side surface of the feature. SDK surface was introduced in #1779 (QVAC-13559).

📝 How is it solved?

• Removed the toolsMode config field from the llamacpp model config schema and the TOOLS_MODE / ToolsMode root exports (breaking)
• Removed appendToolsToHistory and the dynamic branches in completion-stream / batch-completion-stream; tools are always prepended after the system message (the previous default)
• Removed the tools_mode → tools_compact addon config mapping in transform.ts
• Deleted the dynamic e2e tests (tools-simple-function-dynamic, kv-cache-tools-dynamic-reuse), the tools-dynamic consumer resources, and examples/llamacpp-dynamic-tools.ts
• Regenerated contract/schema.json and the sdk-python bindings (ToolsMode enums / tools_mode field gone)
• opencode plugin: dropped the toolsMode: 'static' pin (the field no longer exists; static is the only behavior)
• No version bumps — releasing is deferred to the release flow

🧪 How is it tested?

• bun run build (eslint + tsc), unit tests, prettier, and contract:check all green
• sdk-python scripts/generate.py --check green
• New generateConfigHash unit tests (both trees) pin the cache-identity contract: a changed parameter schema mints a new cache, object-key insertion order does not, and tool-array order does
• A second unit test (both trees) pins the no-tools digests — omitted tools, an empty tool array, and a null system prompt — to the values this PR ships, so a later change to the hash payload or its serialization cannot rename every tool-free cache file unnoticed
• kv-cache-tools-sequential-save now also asserts a declared tool call on both rounds; sampling is pinned (temp: 0, top_k: 1, seed: 42) so the assertion does not depend on the model choosing to call the tool
• The identical SDK content already passed the full PR CI suite on the pre-split combined branch of QVAC-22567 feat[bc]: remove dynamic tools (tools_compact) from llm-llamacpp addon #3373

⚠️ Any breaking changes?

Yes — the TOOLS_MODE value and ToolsMode type root exports are removed (compile-time breaking for any TypeScript consumer importing them), and the toolsMode model-config field is gone.

Stale-config behavior: a leftover toolsMode key is rejected, not ignored. loadModel validates built-in model configs through loadBuiltinToRequestSchema, whose llm branch applies llmConfigBaseSchema.strict(), so an unknown key fails validation and throws RequestValidationFailedError naming modelConfig.toolsMode before the request reaches the server. Callers must remove the key. This matches the addon: #3373 landed without the tools_compact tombstone (see its final commit), and the @qvac/llm-llamacpp 0.43.0 changelog states that configurations passing tools_compact "now fail model loading as an unsupported option". Both layers reject rather than degrade.

One asymmetry worth knowing: SDK config files are parsed through the non-strict llmConfigBaseSchema in sdk-config.ts, which silently strips unknown keys. A toolsMode entry in a config file is therefore dropped and the model loads with static placement, while the same key passed directly to loadModel throws. Both outcomes are safe — the tools_mode → tools_compact mapping is gone, so nothing stale can reach the addon — but the error surfaces only on the direct-call path.

KV-cache impact (one-time, all existing caches). generateConfigHash now digests the complete canonical tool definitions instead of just tool names, so a tool whose parameters or description change no longer reuses a cache whose prefix holds the old tool block. The hash payload key also changed from toolNames to tools, so the serialized form differs from the previous release for every input — including an empty or omitted tool list. Because configHash is the .bin filename, every cache written by an earlier release is invalidated on upgrade, tool-using and plain-chat sessions alike: each re-primes once under a new filename, the old file is left behind, and since retention only reclaims auto-cache markers, caller-owned string keys keep those orphans until deleteCache removes them. Going forward, tool-array order and any change to a tool's name, description, or parameters also mint a new cache, so a caller that varies its tool set per turn (as former dynamic users did) gets a fresh cache file rather than reusing one. Correctness-preserving throughout — the cost is a cold cache and some reclaimable disk.

BEFORE:

// old — SDK dynamic tools mode
import { loadModel, TOOLS_MODE, type ToolsMode } from '@qvac/sdk'

const modelId = await loadModel({
  modelSrc: QWEN3_1_7B_INST_Q4,
  modelType: 'llm',
  modelConfig: { ctx_size: 4096, tools: true, toolsMode: TOOLS_MODE.dynamic }
})

AFTER:

// new — TOOLS_MODE/ToolsMode exports removed; tools are always prepended
// after the system message (the previous static default). The `toolsMode`
// key must be removed: passing it to loadModel now throws a validation
// error rather than being ignored.
import { loadModel } from '@qvac/sdk'

const modelId = await loadModel({
  modelSrc: QWEN3_1_7B_INST_Q4,
  modelType: 'llm',
  modelConfig: { ctx_size: 4096, tools: true }
})

📦 Release coordination (deferred, no version bump in this PR)

Per the no-version-bump plan, these are captured at the next coordinated release rather than in this PR:

• SDK release notes must document the removed public TOOLS_MODE/ToolsMode exports + toolsMode config field, state that the key must be removed (it is rejected, not ignored), note the one-time KV-cache invalidation described above, and version the release as breaking.
• opencode plugin changelog should note that the toolsMode: 'static' pin was dropped (behavior-neutral — static was the default and the key no longer exists) at the plugin's next release.
• Lockstep with QVAC-22567 feat[bc]: remove dynamic tools (tools_compact) from llm-llamacpp addon #3373: the @qvac/sdk release that advances its @qvac/llm-llamacpp dependency past the addon's tools_compact removal must include this change, so no build pairs the old tools_mode→tools_compact mapping with a new addon. This cannot happen silently — the addon shipped the removal as a minor bump (0.43.0) and the SDK pins ^0.39.3, which caret-on-zero-major caps below 0.40.0 — so the requirement binds to the PR that raises that range, not to any existing published build.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1217241821002583

[github-actions]

Review Status

Current Status: ✅ APPROVED
Approvals so far: Team Lead: 1, Member: 1

[github-actions]

License compliance — findings detected (warn-only)

Critical: 0 · High: 2 · Medium: 0

Dependency	License	Scope	Severity	Outcome
@qvac/llm-llamacpp@^0.43.0	(none detected)	development	High	blocks
@qvac/llm-llamacpp@^0.43.0	(none detected)	runtime	High	blocks

How to resolve a blocking finding:

• Remove or replace the disallowed dependency, or
• If the license is genuinely acceptable, run the compliance SKILL and record the decision in .github/license-allowlist.yml (CODEOWNERS-reviewed), or
• For a one-off, a maintainer can apply the license-override label (High findings only; Critical cannot be overridden).

Warn-only (shadow) mode — this check does not block merges yet.

Updated automatically by the canonical license compliance workflow.

NOTICE presence (advisory)

Missing NOTICE (advisory, does not block):

• ./.github/actions/release-merge-guard
• ./docs/website
• ./packages/ggml-coload-smoke
• ./packages/fabric/test/integration
• ./packages/inference-addon-cpp/mobile
• ./packages/sdk/e2e
• ./packages/llm-llamacpp/benchmarks/performance
• ./packages/llm-llamacpp/benchmarks/server
• ./packages/vla-ggml/sim/server
• ./packages/embed-llamacpp/benchmarks/performance
• ./packages/embed-llamacpp/benchmarks/server
• ./packages/asr-ggml/benchmarks/server

[github-actions]

This draft PR is stale because it has been open 21 days and the author has not commented since opening. It is flagged for removal. Remove the stale label or comment on the PR or this will be closed in one day.

[github-actions]

This draft PR is stale because it has been open 21 days and the author has not commented since opening. It is flagged for removal. Remove the stale label or comment on the PR or this will be closed in one day.

[maxim-smotrov]

This PR is still WIP. Waiting for the new LLM version release before opening this for review.

[dev-nid]

qvac/packages/inference/test/completion-kvcache-tools.test.ts

Line 334 in 17a6375

// block only runs in dynamic mode. While the block can be evicted it has to

This comment still references dynamic mode and its protective clamp

[iancris]

/review