KV Tool-Loop Stability
Use this skill when changing Skippy KV slot cleanup, prefix-cache lookup,
OpenAI tool-loop behavior, agent harnesses, or any runtime path related to
llama_decode failed, failed to find a memory slot, low same-prefix cache
reuse, or proactive eviction failures.
Workflow
- Attach to an existing OpenAI-compatible
/v1 endpoint. This harness does
not start nodes, load models, join meshes, or change routing policy.
- Prefer a direct model when reproducing Skippy KV/cache issues. Use
auto
only when intentionally validating routed behavior.
- Run
--print-plan first and confirm the models, attempts,
pressure_turns, timeout, cache thresholds, output directory, and native
logs.
- Pass the active Skippy native log when available. The harness checkpoints
native logs at run start and scans only appended bytes.
- Preserve the evidence directory:
manifest.json, results.jsonl,
summary.json, summary.md, and transcripts/*.jsonl.
Commands
Preview the run without touching the endpoint:
scripts/qa-kv-tool-loop-stability.py \
--base-url http://127.0.0.1:9337/v1 \
--models Qwen/Qwen2.5-3B-Instruct-GGUF:q4_k_m \
--attempts 5 \
--pressure-turns 8 \
--timeout 180 \
--min-cached-tokens 2048 \
--suffix-prefill-limit 256 \
--native-log ~/.mesh-llm/runtime/<pid>/logs/skippy-native.log \
--output-dir target/kv-tool-loop-stability/local \
--print-plan
Run the certification:
scripts/qa-kv-tool-loop-stability.py \
--base-url http://127.0.0.1:9337/v1 \
--models Qwen/Qwen2.5-3B-Instruct-GGUF:q4_k_m \
--attempts 5 \
--pressure-turns 8 \
--timeout 180 \
--min-cached-tokens 2048 \
--suffix-prefill-limit 256 \
--native-log ~/.mesh-llm/runtime/<pid>/logs/skippy-native.log \
--output-dir target/kv-tool-loop-stability/local
Reporting Rules
- Report the model list, attempts, pressure turns, timeout, cache thresholds,
success rate, native log paths, and output directory.
- Include the summary verdict and failing phase details from
summary.md or
summary.json.
- Do not paste full prompts, auth headers, huge stable prefixes, or private
endpoint data.
- If no native log is available, say that native-log scanning was not run.
Validation
When changing this harness, run:
python3 -m unittest scripts.tests.test_qa_kv_tool_loop_stability
python3 -m py_compile scripts/qa-kv-tool-loop-stability.py scripts/tests/test_qa_kv_tool_loop_stability.py
1---2name: kv-tool-loop-stability3description: Use this skill when certifying mesh-llm KV/cache stability under repeated OpenAI tool-call loops, same-prefix cache reuse, suffix-prefill limits, or native Skippy slot/decode/eviction failures.4---56# KV Tool-Loop Stability78Use this skill when changing Skippy KV slot cleanup, prefix-cache lookup,9OpenAI tool-loop behavior, agent harnesses, or any runtime path related to10`llama_decode failed`, `failed to find a memory slot`, low same-prefix cache11reuse, or proactive eviction failures.1213## Workflow14151. Attach to an existing OpenAI-compatible `/v1` endpoint. This harness does16 not start nodes, load models, join meshes, or change routing policy.172. Prefer a direct model when reproducing Skippy KV/cache issues. Use `auto`18 only when intentionally validating routed behavior.193. Run `--print-plan` first and confirm the models, attempts,20 `pressure_turns`, timeout, cache thresholds, output directory, and native21 logs.224. Pass the active Skippy native log when available. The harness checkpoints23 native logs at run start and scans only appended bytes.245. Preserve the evidence directory: `manifest.json`, `results.jsonl`,25 `summary.json`, `summary.md`, and `transcripts/*.jsonl`.2627## Commands2829Preview the run without touching the endpoint:3031```bash32scripts/qa-kv-tool-loop-stability.py \33 --base-url http://127.0.0.1:9337/v1 \34 --models Qwen/Qwen2.5-3B-Instruct-GGUF:q4_k_m \35 --attempts 5 \36 --pressure-turns 8 \37 --timeout 180 \38 --min-cached-tokens 2048 \39 --suffix-prefill-limit 256 \40 --native-log ~/.mesh-llm/runtime/<pid>/logs/skippy-native.log \41 --output-dir target/kv-tool-loop-stability/local \42 --print-plan43```4445Run the certification:4647```bash48scripts/qa-kv-tool-loop-stability.py \49 --base-url http://127.0.0.1:9337/v1 \50 --models Qwen/Qwen2.5-3B-Instruct-GGUF:q4_k_m \51 --attempts 5 \52 --pressure-turns 8 \53 --timeout 180 \54 --min-cached-tokens 2048 \55 --suffix-prefill-limit 256 \56 --native-log ~/.mesh-llm/runtime/<pid>/logs/skippy-native.log \57 --output-dir target/kv-tool-loop-stability/local58```5960## Reporting Rules6162- Report the model list, attempts, pressure turns, timeout, cache thresholds,63 success rate, native log paths, and output directory.64- Include the summary verdict and failing phase details from `summary.md` or65 `summary.json`.66- Do not paste full prompts, auth headers, huge stable prefixes, or private67 endpoint data.68- If no native log is available, say that native-log scanning was not run.6970## Validation7172When changing this harness, run:7374```bash75python3 -m unittest scripts.tests.test_qa_kv_tool_loop_stability76python3 -m py_compile scripts/qa-kv-tool-loop-stability.py scripts/tests/test_qa_kv_tool_loop_stability.py77```