Update README.md & encoding/README.md

.gitattributes

@@ -35,3 +35,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 inference/examples/images/carrots.jpeg filter=lfs diff=lfs merge=lfs -text
 DeepSeek_V41_Tech_Report.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,44 +1,197 @@
 ---
 license: mit
 library_name: transformers
+pipeline_tag: image-text-to-text
 ---
 
-# DeepSeek-V4.1-Exp
+# DeepSeek-V4.1-Flash: Pushing the Limits of KV Cache Compression
 
-Prompt encoding reference and a minimal PyTorch inference implementation for
-DeepSeek-V4.1. The inference code covers the vision encoder and aligner,
-sliding-window plus compressed sparse attention with its two-level indexer,
-engram n-gram lookups, MoE, Hyper-Connections, and the DSpark forward path.
+<!-- markdownlint-disable first-line-h1 -->
+<!-- markdownlint-disable html -->
+<!-- markdownlint-disable no-duplicate-header -->
 
-## Repository layout
+<div align="center">
+  <img src="https://github.com/deepseek-ai/DeepSeek-V2/blob/main/figures/logo.svg?raw=true" width="60%" alt="DeepSeek-V4.1" />
+</div>
+<hr>
+<div align="center" style="line-height: 1;">
+  <a href="https://www.deepseek.com/" target="_blank" style="margin: 2px;">
+    <img alt="Homepage" src="https://github.com/deepseek-ai/DeepSeek-V2/blob/main/figures/badge.svg?raw=true" style="display: inline-block; vertical-align: middle;"/>
+  </a>
+  <a href="https://chat.deepseek.com/" target="_blank" style="margin: 2px;">
+    <img alt="Chat" src="https://img.shields.io/badge/🤖%20Chat-DeepSeek%20V4.1-536af5?color=536af5&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
+  </a>
+</div>
+<div align="center" style="line-height: 1;">
+  <a href="https://huggingface.co/deepseek-ai" target="_blank" style="margin: 2px;">
+    <img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-DeepSeek%20AI-ffc107?color=ffc107&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
+  </a>
+  <a href="https://twitter.com/deepseek_ai" target="_blank" style="margin: 2px;">
+    <img alt="Twitter Follow" src="https://img.shields.io/badge/Twitter-deepseek_ai-white?logo=x&logoColor=white" style="display: inline-block; vertical-align: middle;"/>
+  </a>
+</div>
+<div align="center" style="line-height: 1;">
+  <a href="LICENSE" style="margin: 2px;">
+    <img alt="License" src="https://img.shields.io/badge/License-MIT-f5de53?&color=f5de53" style="display: inline-block; vertical-align: middle;"/>
+  </a>
+</div>
 
-```text
-.
-├── encoding/                  # OpenAI-style messages -> model prompt
-│   └── tests/                 # golden prompt fixtures
-├── inference/                 # weight conversion and minimal inference
-│   └── examples/              # equivalent TXT and JSON prompts
-└── config.json                # Hugging Face model metadata
-```
+<p align="center">
+  <a href="DeepSeek_V41_Tech_Report.pdf"><b>Technical Report</b> 👁️</a>
+</p>
+
+## Introduction
+
+We introduce **DeepSeek-V4.1-Flash**, a multimodal Mixture-of-Experts (MoE) model with 552B backbone parameters and support for contexts of up to one million tokens. The model natively processes images and text, and generates text autoregressively.
+
+**Architecture.** DeepSeek-V4.1-Flash adopts a **Causal Encoder-Decoder (CED)** architecture: a 40-layer Transformer organized as a 20-layer causal encoder followed by a 20-layer decoder. With CED, the decoder's global KV cache is projected from the final encoder hidden states rather than derived from each decoder layer's own hidden states. This allows the model to activate only **8B parameters per token during prefill** and **16B during decode**, substantially improving cost efficiency for input-heavy agentic workloads. **SWA Bounded Replay** reconstructs missing SWA KV states by replaying only the most recent *n*_win tokens, avoiding the need to persist SWA KV to SSD and reducing the persistent KV cache footprint to roughly **1/8** of that of DeepSeek-V4-Flash.
+
+**Compressed Sparse Attention 2 (CSA2).** DeepSeek-V4.1-Flash uses CSA2, which assigns each attention layer one of three static modes — **Full**, **Reindex**, or **Reuse** — to share main KV and indexer K across layers and reuse Top-K sparse-attention indices. In the decoder, a **Hierarchical Sparse Indexer** further restricts later indexing layers to a candidate pool constructed by the first Full Mode layer, bounding deeper indexer cost independently of context length. Combined with **FP4 main KV caching** (E2M1 format, one E4M3 scale per 16 channels), these designs reduce the global KV cache footprint to **890 bytes per token** — roughly **1/4** of DeepSeek-V4-Flash.
+
+**Additional architectural components** include Single-Pass mHC (revised residual-stream mixing with an efficient Mega-mHC kernel), Engram conditional memory (196B parameters, sparsely accessed via token-based lookup), and DSpark speculative decoding (semi-autoregressive draft generation with confidence-scheduled verification). The model uses 1 shared expert and 384 routed experts per MoE layer, activating 6 routed experts per token.
+
+**Multimodal architecture.** A vision encoder (DeepSeek-ViT, trained from scratch with 2D-RoPE and 3×3 pixel-unshuffle downsampling) and a two-layer MLP projector convert images into visual embeddings, processed jointly with text embeddings from the start of language-model pre-training.
+
+**Pre-training.** DeepSeek-V4.1-Flash is trained from scratch on a multimodal corpus comprising **45T tokens**, with sparse attention trained at a sequence length of 64K and context extended to 1M tokens at 34T tokens.
+
+**Post-training.** The post-training recipe follows the standard SFT → RL → on-policy distillation (OPD) paradigm without algorithmic modifications. All substantive changes lie instead in the data pipeline: large-scale automated synthesis of agent tasks and environments with progressive scaling of data, tasks, and rollouts. The model supports a **continuously controllable reasoning effort** setting (integer 1–100) that trades inference cost for accuracy.
+
+<div align="center">
+  <img src="assets/dsv41_agentic_performance.png" width="48%" alt="DeepSeek-V4.1-Flash agentic benchmark performance" style="display: inline-block; margin: 0 1%;" />
+  <img src="assets/dsv41_kv_cache.png" width="48%" alt="Global KV cache size per token across DeepSeek generations" style="display: inline-block; margin: 0 1%;" />
+</div>
+
+*Figure 1. (a) Performance of DeepSeek-V4.1-Flash and counterparts on agentic benchmarks. (b) Global KV cache size per token (bytes) across generations of DeepSeek models. DeepSeek-V4.1-Flash achieves approximately 4-fold and 437-fold reductions relative to DeepSeek-V4-Flash and DeepSeek-V1, respectively.*
+
+## Evaluation Results
+
+### Base Model
+
+All base models are evaluated in our internal framework under the same evaluation settings. Scores within 0.3 of each other are considered equivalent.
+
+<div align="center">
+
+| Benchmark (Metric) | # Shots | DeepSeek-V4-Flash-Base | DeepSeek-V4-Pro-Base | DeepSeek-V4.1-Flash-Base |
+| :--- | :---: | :---: | :---: | :---: |
+| Architecture | — | MoE | MoE | MoE |
+| # Backbone Params | — | 284B | 1.6T | 552B |
+| # Activated Params | — | 13B | 49B | 8B / 16B |
+| **World Knowledge** | | | | |
+| AGIEval (EM) | 3–5-shot | 83.9 | **84.4** | 83.4 |
+| MMLU-Pro (EM) | 5-shot | 68.3 | 73.5 | **74.1** |
+| C-Eval (EM) | 5-shot | 92.1 | **93.1** | 92.1 |
+| MultiLoKo (LLM-Judge) | 5-shot | 42.6 | **50.9** | 45.5 |
+| SimpleQA-Verified (EM) | 25-shot | 30.1 | **55.2** | 42.3 |
+| SuperGPQA (EM) | 5-shot | 46.5 | **53.9** | 53.1 |
+| **Language & Reasoning** | | | | |
+| BBH (EM) | 3-shot | 86.9 | **87.5** | 86.1 |
+| BBEH (EM) | 1-shot | 25.4 | **29.8** | 27.2 |
+| DROP (F1) | 1-shot | **88.6** | **88.7** | 87.9 |
+| HellaSwag (EM) | 0-shot | 85.7 | **88.0** | 87.2 |
+| **Code & Math** | | | | |
+| BigCodeBench (Pass@1) | 3-shot | 56.8 | 59.2 | **60.6** |
+| HumanEval (Pass@1) | 0-shot | 69.5 | 76.8 | **79.4** |
+| GSM8K (EM) | 8-shot | 90.8 | 92.6 | **93.0** |
+| MATH (EM) | 4-shot | 57.4 | **64.5** | 61.1 |
+| MGSM (EM) | 8-shot | **85.7** | 84.4 | 80.2 |
+| **Long Context** | | | | |
+| LongBench-V2 (EM) | 1-shot | 44.7 | **51.5** | 45.2 |
+| **Multimodal** | | | | |
+| MMMU-Pro (EM) | 4-shot | — | — | 56.5 |
+| CVBench (EM) | 4-shot | — | — | 77.9 |
+| DocVQA (LLM-Judge) | 4-shot | — | — | 95.6 |
+| RefCOCO-avg (Acc@0.5) | 0-shot | — | — | 86.0 |
+
+</div>
+
+### Instruct Model
+
+DeepSeek-V4.1-Flash supports a continuously controllable reasoning effort from 1 to 100. All instruct results below use the maximum effort setting (`reasoning_effort=100`). Evaluations use `temperature=1.0, top_p=0.95`.
 
-`encoding/` and `inference/` deliberately remain separate: prompt formatting
-does not depend on PyTorch, while inference imports the sibling encoding module
-with an explicit Python path. No symlinks are required.
+For code agent benchmarks (Terminal Bench 2.1/3.0/4.0, DeepSWE v1.1, NL2Repo-Bench, ProgramBench), the model is evaluated with the Minimal mode of DeepSeek Harness and a 1M-token context window, except DeepSWE v1.1 which additionally reports results with the mini-SWE harness to align with the official evaluation. Visual agent benchmarks (Chartography, BabyVision, ZeroBench) use Claude Code harness with a 512k-token context window. Agent's Last Exam and AutomationBench use their official scaffolds.
 
-Weights, `model.safetensors.index.json`, `generation_config.json`, and the
-tokenizer files live in the Hugging Face weight repository, not here.
+#### Comparison with frontier models (Max reasoning effort)
 
-## Prompt encoding
+<div align="center">
 
-See [`encoding/README.md`](encoding/README.md). Both OpenAI-style JSON content
-blocks and the compact `<image>path</image>` TXT notation are supported. The two
-examples under `inference/examples/` encode to identical prompts and token IDs.
+| Benchmark (Metric) | Opus-5.0 | GPT-5.6 Sol | K3 | GLM-5.3 | DS-V4-Pro | DS-V4-Flash | DS-V4.1-Flash |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| **Reasoning** | | | | | | | |
+| GPQA Diamond (Pass@1) | 93.4 | **94.1** | 92.9 | 88.1 | 92.4 | 89.9 | 90.9 |
+| HLE (Pass@1) | **56.3** | 44.5 | 43.5 | 42.0† | 42.7† | 37.8† | 36.8 (39.1†) |
+| Codeforces (Rating) | — | — | — | — | 3348 | 3289 | **3471** |
+| MathArena Apex (Pass@1) | — | — | **65.6** | — | 65.3 | 58.6 | **65.6** |
+| **Agentic** | | | | | | | |
+| Terminal Bench 2.1 (Pass@1) | 89.1 | 88.8 | 88.3 | 88.2 | 87.9 | 82.7 | **90.6** |
+| Terminal Bench 3.0 (Pass@1) | **43.3** | 34.4 | 17.7 | 28.3 | 11.8 | 7.6 | 30.0 |
+| Terminal Bench 4.0 (Pass@1) | **51.8** | 39.9 | 12.6 | 37.9 | 12.4 | 7.0 | 31.2 |
+| DeepSWE v1.1 (Resolved) | 74.0 | 73.0 | 67.5 | 66.9 | 62.7 | 54.4 | **74.2** |
+| ProgramBench (Almost@1) | **37.0** | 23.0 | 17.5 | 19.0 | 15.5 | — | 20.3 |
+| NL2Repo-Bench (Score) | **75.3** | 56.8 | 58.0 | 58.0 | 61.5 | 54.2 | 64.0 |
+| CyberGym (Pass@1) | — | 84.5 | 80.0 | 84.5 | 83.3 | 76.7 | **88.1** |
+| SEC-Bench Pro (Pass@1) | — | **74.3** | — | — | 56.4 | 30.9 | 62.8 |
+| ExploitGym (Pass@1) | 22.1 | **33.7** | — | 15.0 | 5.4 | 1.8 | 15.3 |
+| HLE w/ tools (Pass@1) | 63.6 | — | 59.8 | 62.5 | 60.0 | 51.5 | **63.9** |
+| AutomationBench (Pass@1) | 50.3 | 45.8 | 46.7 | 48.8 | 43.2 | 37.7 | **54.8** |
+| Agent's Last Exam (Pass@1) | 28.6 | 26.7 | 27.6 | 28.5 | 25.7 | 25.2 | **31.8** |
+| Chartography w/ tools (Pass@1) | **84.0** | 79.9 | 68.1 | — | — | — | 78.9 |
+| BabyVision w/ tools (Pass@1) | **94.1** | 88.9 | 85.7 | — | — | — | 89.6 |
+| ZeroBench-main w/ tools (Pass@5) | 52.0 | **53.0** | 41.0 | — | — | — | 49.0 |
 
-## Minimal inference
+</div>
 
-See [`inference/README.md`](inference/README.md) for dependency installation,
-checkpoint conversion, and TXT/JSON inference commands.
+*† Text-only subset of HLE.*
+
+#### Performance across agent scaffolds (DeepSWE v1.1 and Terminal Bench 2.1, Max reasoning effort)
+
+All scaffolds use N=8 samples per task on DeepSWE v1.1 and N=3 on Terminal Bench 2.1, with Linux containers, `temperature=1.0`, `top_p=0.95`, a 1M-token context limit, and max_steps=500 per agent.
+
+<div align="center">
+
+| Benchmark (Metric) | Claude Code | Codex | OpenCode | Pi | mini-SWE | DSH Minimal | DSH Standard | DSH PTC |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| DeepSWE v1.1 (Resolved) | 69.8 | 65.6 | 65.5 | 66.2 | 74.2 | 72.6 | 70.5 | 67.6 |
+| Terminal Bench 2.1 (Pass@1) | 88.0 | 84.1 | 85.0 | 86.1 | 90.3 | 90.6 | 85.8 | 85.8 |
+
+</div>
+
+## Prompt Encoding
+
+This release does not include a Jinja-format chat template. The [`encoding`](encoding/README.md) folder contains a self-contained Python reference implementation (`encoding.py`) with test cases for multi-turn conversations, tool calling, thinking mode, numeric reasoning effort, mid-conversation system messages, and interleaved image content.
+
+For production use, we additionally release [deepseek-recipe](https://github.com/deepseek-ai/deepseek-recipe), a set of Rust libraries with Python bindings that provides the same prompt format as a maintained, protocol-aware toolkit. It converts Messages, Chat Completions, and Responses API requests into the Conversation format, encodes them into DeepSeek V4 and V4.1 prompts or token IDs, and parses model output back into complete or streamed responses — covering thinking, tool calls, images, and generation settings. Model inference, tool execution, and HTTP transport are left to the caller.
+
+## Minimal Inference
+
+Please refer to the [`inference`](inference/README.md) folder for instructions on weight conversion and running inference locally.
+
+**Recommended sampling parameters:**
+
+| Parameter | Value |
+| :--- | :--- |
+| `temperature` | 1.0 |
+| `top_p` | 0.95 or 1.0 |
+| `context_window` | 1M tokens |
+| `max_tokens` | ≥ 256K |
+
+## Reproducing DeepSWE Benchmark Results
+
+The [`evaluation`](evaluation/README.md) folder contains step-by-step instructions for reproducing the DeepSWE v1.1 benchmark results, covering both the `dsh-minimal` agent and the official `mini-swe-agent`. The patch required to integrate `dsh-minimal` with [Pier](https://github.com/datacurve-ai/pier) is also included there.
 
 ## License
 
-This repository is licensed under the [MIT License](LICENSE).
+This repository and the model weights are licensed under the [MIT License](LICENSE).
+
+## Citation
+
+```bibtex
+@misc{deepseekai2026deepseekv41flash,
+      title={DeepSeek-V4.1-Flash: Pushing the Limits of KV Cache Compression},
+      author={DeepSeek-AI},
+      year={2026},
+}
+```
+
+## Contact
+
+If you have any questions, please raise an issue or contact us at [service@deepseek.com](mailto:service@deepseek.com).

encoding/README.md

@@ -1,9 +1,64 @@
 # DeepSeek-V4.1 text and vision encoding
 
-`encoding.py` is the standalone prompt-format reference. It supports multi-turn
-conversations, tool calls, thinking modes, and interleaved image content blocks
+`encoding.py` is the standalone prompt-format reference for DeepSeek-V4.1. It
+supports multi-turn conversations, tool calls, thinking modes, numeric reasoning
+effort, mid-conversation system messages, and interleaved image content blocks,
 without importing the inference implementation.
 
+## V4.1 changes relative to V4
+
+Three prompt-format changes distinguish V4.1 from V4:
+
+1. **DSML tag names use a leading space.** Tool calls are wrapped in
+   `<｜DSML｜ calls>` blocks with `<｜DSML｜ invoke>` / `<｜DSML｜ parameter>` tags
+   (note the space before `calls`, `invoke`, and `parameter`). The V4 format used
+   `<｜DSML｜tool_calls>` without a space.
+
+2. **Reasoning effort is a numeric budget (1–100).** The effort prefix is
+   rendered as `Reasoning Effort: {budget} (range 1-100, ...)` rather than the
+   verbose natural-language descriptions used in V4. String aliases map as
+   follows: `"low"` → 25, `"high"` → 50, `"xhigh"` → 75, `"max"` → 100. The
+   default is `"high"` (50). The effort prefix is only rendered in
+   `thinking_mode="thinking"` and only at the beginning of the conversation
+   (index 0).
+
+3. **Mid-conversation system messages** are supported via the `<｜System｜>` token.
+   A mid-conversation system message behaves like a user message for the purpose
+   of appending the assistant generation header.
+
+## Quick start
+
+```python
+from encoding import encode_messages, parse_message_from_completion_text
+
+# Text-only conversation
+messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What is 2+2?"},
+]
+prompt, media = encode_messages(
+    messages,
+    thinking_mode="thinking",
+    reasoning_effort=75,           # integer 1–100, or "low"/"high"/"xhigh"/"max"
+    return_multi_modal_data=True,
+)
+# prompt:
+# '<｜begin▁of▁sentence｜><｜System｜>Reasoning Effort: 75 (range 1-100, the higher the
+#  value, the more thorough the reasoning)\n\nYou are a helpful assistant.
+#  <｜User｜>What is 2+2?<｜Assistant｜><think>'
+
+# Parse model output back to a structured message
+completion = "Simple arithmetic.</think>2 + 2 = 4.<｜end▁of▁sentence｜>"
+parsed = parse_message_from_completion_text(completion, thinking_mode="thinking")
+# => {"role": "assistant", "reasoning_content": "Simple arithmetic.",
+#     "content": "2 + 2 = 4.", "tool_calls": []}
+```
+
+> **Note:** `parse_message_from_completion_text` is designed to handle
+> well-formatted model output only. It does not attempt to correct or recover
+> from malformed output that the model might occasionally generate. For
+> production use, additional error handling is recommended.
+
 ## OpenAI-style messages
 
 ```python
@@ -26,11 +81,14 @@ prompt, media = encode_messages(
     thinking_mode="chat",
     return_multi_modal_data=True,
 )
+# prompt:
+# '<｜begin▁of▁sentence｜><｜User｜>第一张图\n\n<｜deepseek_image｜>\n\n有什么内容？<｜Assistant｜></think>'
+# media["images"] contains the image records in prompt order
 ```
 
 Images are represented in the prompt by `<｜deepseek_image｜>`. `media["images"]`
-contains the corresponding image records in exactly the same order. Pixel
-loading and expansion into model image tokens are handled by
+contains the corresponding image records in exactly the same order they appear in
+the prompt. Pixel loading and expansion into model image tokens are handled by
 `inference/image_processor.py`.
 
 ## Compact TXT notation
@@ -44,6 +102,162 @@ loading and expansion into model image tokens are handled by
 into the same standard content blocks. It is an input convenience layer, not a
 second encoding implementation.
 
+## Message format
+
+### Special tokens
+
+| Token | Purpose |
+| :--- | :--- |
+| `<｜begin▁of▁sentence｜>` | Beginning of sequence (BOS) |
+| `<｜end▁of▁sentence｜>` | End of assistant turn (EOS) |
+| `<｜User｜>` | User turn prefix |
+| `<｜Assistant｜>` | Assistant turn prefix |
+| `<｜System｜>` | Mid-conversation system message prefix |
+| `<｜latest_reminder｜>` | Latest reminder (date, locale, etc.) |
+| `<think>` / `</think>` | Reasoning block delimiters |
+| `｜DSML｜` | DSML markup token |
+| `<｜deepseek_image｜>` | Image placeholder in the prompt string |
+
+### Roles
+
+The encoding supports the following message roles: `system`, `user`, `assistant`,
+`tool`, and `latest_reminder`.
+
+A `tool` message is not rendered directly: `merge_tool_messages()` converts it
+into a `<tool_result>` block inside the preceding user message. When multiple
+tool results are present, they are sorted by the order of the corresponding
+`tool_calls` in the preceding assistant message.
+
+### Basic chat
+
+A simple multi-turn conversation is encoded as:
+
+```
+<｜begin▁of▁sentence｜>{system_prompt}
+<｜User｜>{user_message}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>
+<｜User｜>{user_message_2}<｜Assistant｜></think>{response_2}<｜end▁of▁sentence｜>
+```
+
+- The BOS token is prepended at the very beginning of the conversation.
+- In **chat mode** (`thinking_mode="chat"`), `</think>` is placed right after
+  `<｜Assistant｜>` to immediately close the thinking block, so the model generates
+  content directly.
+
+### Thinking mode
+
+In **thinking mode** (`thinking_mode="thinking"`), the model produces explicit
+reasoning inside `<think>...</think>` blocks before responding.
+
+```
+<｜begin▁of▁sentence｜><｜System｜>{reasoning_effort_prefix}{system_prompt}
+<｜User｜>{message}<｜Assistant｜><think>{reasoning}</think>{response}<｜end▁of▁sentence｜>
+```
+
+The reasoning effort prefix is injected once, before the system message, as a
+`<｜System｜>` block:
+
+```
+<｜System｜>Reasoning Effort: {budget} (range 1-100, the higher the value, the more thorough the reasoning)
+```
+
+The `drop_thinking` parameter (default `True`) controls whether reasoning from
+earlier turns is preserved:
+
+- **Without tools**: reasoning content from assistant turns **before** the last
+  user message is stripped. Only the final assistant turn retains its
+  `<think>...</think>` block.
+- **With tools**: `drop_thinking` is automatically disabled. All turns retain
+  their reasoning, because tool-calling conversations require full context for
+  the model to track multi-step reasoning across tool calls.
+
+### Tool calling (DSML format)
+
+Tools are defined on the `system` message via the `tools` field
+(OpenAI-compatible format). When tools are present, the following schema block is
+injected into the system prompt:
+
+```
+## Tools
+
+You have access to a set of tools to help answer the user's question. You can invoke tools by writing a "<｜DSML｜ calls>" block like the following:
+
+<｜DSML｜ calls>
+<｜DSML｜ invoke name="$TOOL_NAME">
+<｜DSML｜ parameter name="$PARAMETER_NAME" string="true|false">$PARAMETER_VALUE</｜DSML｜ parameter>
+...
+</｜DSML｜ invoke>
+<｜DSML｜ invoke name="$TOOL_NAME2">
+...
+</｜DSML｜ invoke>
+</｜DSML｜ calls>
+
+String parameters should be specified as is and set `string="true"`. For all other types (numbers, booleans, arrays, objects), pass the value in JSON format and set `string="false"`.
+
+If thinking_mode is enabled (triggered by <think>), you MUST output your complete reasoning inside <think>...</think> BEFORE any tool calls or final response.
+
+Otherwise, output directly after </think> with tool calls or final response.
+
+### Available Tool Schemas
+
+{tool_definitions_json}
+
+You MUST strictly follow the above defined tool name and parameter schemas to invoke tool calls.
+```
+
+An actual tool call in the assistant turn looks like:
+
+```xml
+
+<｜DSML｜ calls>
+<｜DSML｜ invoke name="function_name">
+<｜DSML｜ parameter name="param" string="true">string_value</｜DSML｜ parameter>
+<｜DSML｜ parameter name="count" string="false">5</｜DSML｜ parameter>
+</｜DSML｜ invoke>
+</｜DSML｜ calls><｜end▁of▁sentence｜>
+```
+
+- `string="true"`: the parameter value is a raw string.
+- `string="false"`: the parameter value is JSON (number, boolean, array, object).
+
+Tool execution results are wrapped in `<tool_result>` tags within user messages:
+
+```
+<｜User｜><tool_result>{result_json}</tool_result><｜Assistant｜><think>...
+```
+
+### Reasoning effort
+
+Pass `reasoning_effort` as an integer in `[1, 100]` or as one of `"low"` (25),
+`"high"` (50), `"xhigh"` (75), or `"max"` (100). The default is `"high"` (50).
+The setting only affects `thinking_mode="thinking"` and is only rendered at the
+start of the conversation (index 0). Intermediate values may be used to elicit
+interpolated reasoning behavior.
+
+### Quick instruction special tokens
+
+Quick instruction tokens are used for auxiliary classification and generation
+tasks. They are appended to messages via the `"task"` field to trigger
+specialized model behavior for a single-token or short-form output.
+
+| Special Token | Description | Format |
+|:---|:---|:---|
+| `<｜action｜>` | Determines whether the user prompt requires a web search or can be answered directly. | `...<｜User｜>{prompt}<｜Assistant｜><think><｜action｜>` |
+| `<｜title｜>` | Generates a concise conversation title after the first assistant response. | `...<｜Assistant｜>{response}<｜end▁of▁sentence｜><｜title｜>` |
+| `<｜query｜>` | Generates search queries for the user prompt. | `...<｜User｜>{prompt}<｜query｜>` |
+| `<｜authority｜>` | Classifies the user prompt's demand for source authoritativeness. | `...<｜User｜>{prompt}<｜authority｜>` |
+| `<｜domain｜>` | Identifies the domain of the user prompt. | `...<｜User｜>{prompt}<｜domain｜>` |
+| `<｜read_url｜>` | Determines whether each URL in the user prompt should be fetched and read. | `...<｜User｜>{prompt}<｜read_url｜>` |
+
+Usage in message format:
+
+- **`action`** on a user message: the `<｜action｜>` token is placed after the
+  assistant prefix and thinking token, triggering a routing decision (e.g.,
+  "Search" or "Answer").
+- **Other tasks** (`query`, `authority`, `domain`, `read_url`) on a user message:
+  the task token is appended directly after the user content.
+- **`title`** on an assistant message: the `<｜title｜>` token is appended after
+  the assistant's EOS. The next assistant message provides the generated title.
+
 ## Tests
 
 From this directory:
@@ -52,5 +266,8 @@ From this directory:
 python -m pytest -q test_encoding.py
 ```
 
-The tests include a check that the TXT and JSON examples encode to the same
+Test cases are stored as paired JSON input / TXT expected-output files under
+`tests/`. The tests cover multi-turn conversations, tool calling, thinking mode,
+numeric reasoning effort, mid-conversation system messages, and multimodal image
+ordering. They include a check that the TXT and JSON examples encode to the same
 prompt and preserve the same image ordering.

evaluation/README.md

@@ -0,0 +1,103 @@
+# Running DeepSWE with `dsh-minimal` and `mini-swe-agent`
+
+## 1. Prerequisites
+
+- Docker, running and able to pull images
+- Python 3.12+ and [uv](https://docs.astral.sh/uv/)
+- An endpoint and key for any DeepSeek-API-compatible service (the DeepSeek official API is used as the example below)
+
+```sh
+export DEEPSEEK_API_KEY=sk-your-key-here
+export DEEPSEEK_BASE_URL=https://api.deepseek.com
+```
+
+## 2. Get Pier and DeepSWE
+
+```sh
+git clone https://github.com/datacurve-ai/pier.git
+git -C pier checkout 0c802fc067a425345b24d1c69411aa98acf61a1d
+
+git clone https://github.com/datacurve-ai/deep-swe.git
+git -C deep-swe checkout 0b9fabbb63b9104d678fe965e1632f2dd9eaa2ea
+```
+
+## 3. Patch and install Pier
+
+`dsh-minimal.patch` ships next to this document. Treat it as a **reference patch** and adapt it to your own setup.
+
+```sh
+cd pier
+git apply /path/to/dsh-minimal.patch
+uv sync
+```
+
+What the patch changes:
+
+- **Adds the `dsh-minimal` agent**, which drives the Harness SDK and folds its event stream into a Pier ATIF trajectory. The SDK artifact is never installed into the image: step 4's `--mounts-json` bind-mounts it read-only into the sandbox, so no trial installs anything.
+- **Appends a runtime-constraints section to the task instruction for both agents**: work in `/app`, leave `/tests` alone, no network or package mirror.
+- **Passes test-runner concurrency caps into the container**: Docker's `--cpus` is only a quota, so `nproc` inside the container reports the host's core count and test runners size their worker pools from that rather than from the container's share.
+- **Enables IPv6 loopback in the container**: Docker disables it by default, so suites that bind `::1` are skipped and scored as failures.
+- **Makes `--mounts-json` additive instead of replacing the default mounts**, keeping the `/logs` binds that carry agent logs and collected patches.
+
+## 4. Run the suite
+
+Both agents take the same task set, concurrency, and `--no-delete` (which keeps the task images cached between trials). Repeat each run with a different `--job-name` and average the results.
+
+Each trial's container takes the 2 CPUs and 8 GB its task declares, so size `-n` against the host's cores and memory.
+
+### `mini-swe-agent`
+
+Pier installs it into each task image at trial time, so no host-side preparation is needed.
+
+```sh
+uv run pier run \
+  -p ../deep-swe/tasks \
+  --agent mini-swe-agent \
+  --model deepseek/deepseek-flash \
+  --ak reasoning_effort=max \
+  --ak cost_limit=0 \
+  --ae DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  --ae DEEPSEEK_BASE_URL="$DEEPSEEK_BASE_URL" \
+  -n 32 --no-delete -r 2 --job-name deepswe-mini-run1 -y
+```
+
+- `--model` takes a litellm-style `provider/model` string.
+
+### `dsh-minimal`
+
+Install the Harness SDK artifact once on the host, then bind-mount it read-only into every container.
+
+```sh
+mkdir -p ~/dsh-minimal && cd ~/dsh-minimal
+uv pip install --target dsh-dist \
+  --python-version 3.12 --python-platform x86_64-manylinux_2_28 \
+  'deepseek-harness-sdk==0.1.5.*'
+```
+
+```sh
+uv run pier run \
+  -p ../deep-swe/tasks \
+  --agent dsh-minimal \
+  --model deepseek-flash \
+  --ak reasoning_effort=max \
+  --ae DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  --ae DEEPSEEK_BASE_URL="$DEEPSEEK_BASE_URL" \
+  --mounts-json '[{"type":"bind","source":"'"$HOME"'/dsh-minimal/dsh-dist","target":"/opt/dsh-minimal","read_only":true}]' \
+  -n 32 --no-delete --job-name deepswe-dsh-run1 -y
+```
+
+- In `--mounts-json`, `source` is the absolute path of the `dsh-dist` directory above; `target` is always `/opt/dsh-minimal`.
+
+## 5. Read the results
+
+```
+jobs/<job-name>/
+  result.json              pass rate and token totals
+  <task>__<id>/
+    result.json            reward, fail-to-pass / pass-to-pass counts, tokens
+    agent/trajectory.json  full ATIF trajectory (dsh-minimal)
+    agent/mini-swe-agent.trajectory.json   mini-swe-agent trajectory
+    verifier/              reward.json and test output
+```
+
+Browse a job with `uv run pier view jobs/<job-name>`.

evaluation/dsh-minimal.patch

@@ -0,0 +1,711 @@
+diff --git a/src/pier/agents/factory.py b/src/pier/agents/factory.py
+index 665fadd..503a45d 100644
+--- a/src/pier/agents/factory.py
++++ b/src/pier/agents/factory.py
+@@ -6,6 +6,7 @@ from pier.agents.installed.antigravity_sdk import AntigravitySDK
+ from pier.agents.installed.claude_code import ClaudeCode
+ from pier.agents.installed.codex import Codex
+ from pier.agents.installed.cursor_cli import CursorCli
++from pier.agents.installed.dsh_minimal import DshMinimal
+ from pier.agents.installed.gemini_cli import GeminiCli
+ from pier.agents.installed.mini_swe_agent import MiniSweAgent
+ from pier.agents.installed.opencode import OpenCode
+@@ -24,6 +25,7 @@ class AgentFactory:
+         ClaudeCode,
+         Codex,
+         CursorCli,
++        DshMinimal,
+         GeminiCli,
+         MiniSweAgent,
+         OpenCode,
+diff --git a/src/pier/agents/installed/base.py b/src/pier/agents/installed/base.py
+index 16f6a84..1fd1050 100644
+--- a/src/pier/agents/installed/base.py
++++ b/src/pier/agents/installed/base.py
+@@ -15,6 +15,18 @@ from pier.utils.env import parse_bool_env_value
+ from pier.utils.templating import render_prompt_template
+ 
+ 
++RUNTIME_CONSTRAINTS = (
++    "\n## Runtime constraints\n"
++    "- Work in `/app`; do not modify files under `/tests`.\n"
++    "- No network or mirror access; use only dependencies already in the image.\n"
++)
++
++
++def with_runtime_constraints(instruction: str) -> str:
++    """Append the sandbox constraints to a task instruction."""
++    return instruction.rstrip("\n") + "\n" + RUNTIME_CONSTRAINTS
++
++
+ class NonZeroAgentExitCodeError(RuntimeError):
+     """Raised when the agent process exits with a non-zero exit code."""
+ 
+@@ -394,12 +406,14 @@ class BaseInstalledAgent(BaseAgent, ABC):
+         return instruction
+ 
+     @abstractmethod
+-    def install_spec(self) -> AgentInstallSpec:
+-        """Declarative install steps executed at setup and inlined into Dockerfile builds."""
++    def install_spec(self) -> AgentInstallSpec | None:
++        """Declarative install steps executed at setup and inlined into Dockerfile
++        builds, or ``None`` for an agent already present in the environment."""
+ 
+     async def install(self, environment: BaseEnvironment) -> None:
+         """Run each step from :meth:`install_spec` with matching privilege."""
+-        for step in self.install_spec().steps:
++        spec = self.install_spec()
++        for step in spec.steps if spec is not None else ():
+             if step.user == "root":
+                 await self.exec_as_root(environment, command=step.run, env=step.env)
+             else:
+diff --git a/src/pier/agents/installed/dsh_minimal.py b/src/pier/agents/installed/dsh_minimal.py
+new file mode 100644
+index 0000000..c84a1b1
+--- /dev/null
++++ b/src/pier/agents/installed/dsh_minimal.py
+@@ -0,0 +1,131 @@
++import shlex
++from pathlib import Path
++from typing import Any, override
++
++from pier.agents.installed.base import (
++    BaseInstalledAgent,
++    with_prompt_template,
++    with_runtime_constraints,
++)
++from pier.agents.network import allowlist_from_urls
++from pier.environments.base import BaseEnvironment
++from pier.models.agent.context import AgentContext
++from pier.models.agent.name import AgentName
++from pier.models.agent.network import NetworkAllowlist
++from pier.models.trajectories import Trajectory
++from pier.utils.trajectory_metrics import populate_context_from_final_metrics
++
++DIST = "/opt/dsh-minimal"
++DEFAULT_MODEL = "deepseek-flash"
++DEFAULT_BASE_URL = "https://api.deepseek.com"
++REASONING_EFFORTS = ("low", "high", "max")
++
++
++class DshMinimal(BaseInstalledAgent):
++    """DeepSeek Harness `sdk-minimal` profile driven through its Python SDK.
++
++    The SDK and its bundled runtime executable come from a `pip install --target`
++    tree bind-mounted read-only at ``DIST``, so no trial installs anything.
++    """
++
++    SUPPORTS_ATIF = True
++    _TRAJECTORY = "trajectory.json"
++    # The distribution mount is read-only, so the runner lands beside it.
++    _RUNNER = "/tmp/dsh-minimal-runner.py"
++
++    def __init__(
++        self, *args: Any, reasoning_effort: str = "max", **kwargs: Any
++    ) -> None:
++        if reasoning_effort not in REASONING_EFFORTS:
++            raise ValueError(
++                f"reasoning_effort must be one of {REASONING_EFFORTS}, "
++                f"got {reasoning_effort!r}"
++            )
++        self._reasoning_effort = reasoning_effort
++        kwargs["model_name"] = kwargs.get("model_name") or DEFAULT_MODEL
++        super().__init__(*args, **kwargs)
++
++    @staticmethod
++    @override
++    def name() -> str:
++        return AgentName.DSH_MINIMAL.value
++
++    @override
++    def install_spec(self) -> None:
++        """The distribution is bind-mounted, so no image layer is needed."""
++        return None
++
++    @override
++    def get_version_command(self) -> str:
++        return f"sed -n 's/^Version: //p' {DIST}/deepseek_harness_sdk-*.dist-info/METADATA"
++
++    @override
++    async def setup(self, environment: BaseEnvironment) -> None:
++        await super().setup(environment)
++        runner = Path(__file__).with_name("dsh_minimal_runner.py")
++        await environment.upload_file(runner, self._RUNNER)
++        await self.exec_as_root(environment, f"chmod a+r {self._RUNNER}")
++
++    def _base_url(self) -> str:
++        return self._get_env("DEEPSEEK_BASE_URL") or DEFAULT_BASE_URL
++
++    @override
++    def network_allowlist(self) -> NetworkAllowlist:
++        return allowlist_from_urls([self._base_url()])
++
++    @override
++    def populate_context_post_run(self, context: AgentContext) -> None:
++        path = self.logs_dir / self._TRAJECTORY
++        if not path.exists():
++            self.logger.debug("No dsh-minimal trajectory found at %s", path)
++            return
++        try:
++            trajectory = Trajectory.model_validate_json(path.read_text())
++        except (OSError, ValueError):
++            self.logger.exception("Failed to parse dsh-minimal trajectory")
++            return
++        if trajectory.final_metrics is not None:
++            populate_context_from_final_metrics(context, trajectory.final_metrics)
++        context.n_agent_steps = sum(step.source == "agent" for step in trajectory.steps)
++
++    @override
++    @with_prompt_template
++    async def run(
++        self,
++        instruction: str,
++        environment: BaseEnvironment,
++        context: AgentContext,
++    ) -> None:
++        api_key = self._get_env("DEEPSEEK_API_KEY")
++        if not api_key:
++            raise ValueError("DEEPSEEK_API_KEY environment variable must be set")
++
++        instruction = with_runtime_constraints(instruction)
++        agent_dir = environment.env_paths.agent_dir.as_posix()
++        env = self.build_process_env(
++            {
++                "DEEPSEEK_API_KEY": api_key,
++                "DEEPSEEK_BASE_URL": self._base_url(),
++                # The Node runtime reaches the model only through Pier's egress
++                # proxy, and its fetch ignores the proxy variables without this.
++                "NODE_USE_ENV_PROXY": "1",
++                "PYTHONPATH": DIST,
++                "DSH_MODEL": self._parsed_model_name,
++                "DSH_REASONING_EFFORT": self._reasoning_effort,
++                # Required, and kept off the /logs bind mount: it materializes many
++                # files the host cannot read anyway. `trajectory.json` is the record.
++                "DSH_HOME": "/tmp/dsh-home",
++                "SESSION_ID": environment.session_id,
++            }
++        )
++
++        await self.exec_as_agent(
++            environment,
++            command=(
++                f"python3 {self._RUNNER} "
++                f"--instruction {shlex.quote(instruction)} "
++                f"--trajectory-path {agent_dir}/{self._TRAJECTORY} "
++                f"2>&1 </dev/null | stdbuf -oL tee {agent_dir}/dsh-minimal.txt"
++            ),
++            env=env,
++        )
+diff --git a/src/pier/agents/installed/dsh_minimal_runner.py b/src/pier/agents/installed/dsh_minimal_runner.py
+new file mode 100644
+index 0000000..8b69d7d
+--- /dev/null
++++ b/src/pier/agents/installed/dsh_minimal_runner.py
+@@ -0,0 +1,307 @@
++"""Run the DeepSeek Harness `sdk-minimal` profile and persist its stream as ATIF v1.7."""
++
++from __future__ import annotations
++
++import argparse
++import json
++import os
++import sys
++import traceback
++from datetime import datetime, timezone
++from importlib.metadata import PackageNotFoundError, version
++from pathlib import Path
++from typing import Any
++
++from deepseek_harness import DeepSeekHarness
++from deepseek_harness.models import Notification
++
++PROVIDER = "deepseek-official"
++
++
++def _iso(epoch_ms: Any) -> str | None:
++    if not isinstance(epoch_ms, (int, float)):
++        return None
++    return datetime.fromtimestamp(epoch_ms / 1000, tz=timezone.utc).isoformat()
++
++
++def _text(blocks: Any, kind: str) -> str:
++    if not isinstance(blocks, list):
++        return ""
++    return "".join(
++        str(block.get("text") or "")
++        for block in blocks
++        if isinstance(block, dict) and block.get("type") == kind
++    )
++
++
++def _flatten(blocks: Any) -> str:
++    if isinstance(blocks, str):
++        return blocks
++    if not isinstance(blocks, list):
++        return json.dumps(blocks, ensure_ascii=False)
++    return "".join(
++        str(block.get("text") or "")
++        if isinstance(block, dict) and block.get("type") == "text"
++        else json.dumps(block, ensure_ascii=False)
++        for block in blocks
++    )
++
++
++def _arguments(raw: Any) -> dict[str, Any]:
++    """ATIF wants an object; the wire carries the model's raw argument string."""
++    if isinstance(raw, dict):
++        return raw
++    if isinstance(raw, str):
++        try:
++            parsed = json.loads(raw)
++        except json.JSONDecodeError:
++            return {"_unparsed_arguments": raw}
++        return parsed if isinstance(parsed, dict) else {"_arguments": parsed}
++    return {}
++
++
++def _metrics(usage: dict[str, Any]) -> dict[str, Any]:
++    """The adapter reports disjoint counts, so the cache legs rejoin prompt tokens."""
++    cache_read = usage.get("cacheReadTokens") or 0
++    cache_write = usage.get("cacheWriteTokens") or 0
++    metrics = {
++        "prompt_tokens": (usage.get("inputTokens") or 0) + cache_read + cache_write,
++        "completion_tokens": usage.get("outputTokens") or 0,
++        "cached_tokens": cache_read,
++    }
++    if usage.get("reasoningTokens") is not None:
++        metrics["extra"] = {"reasoning_tokens": usage["reasoningTokens"]}
++    return metrics
++
++
++class Collector:
++    """Fold root-session events into one ATIF step per model call."""
++
++    def __init__(self, instruction: str, model: str, effort: str, session: str) -> None:
++        self.model = model
++        self.effort = effort
++        self.session = session
++        self.steps: list[dict[str, Any]] = [
++            {
++                "step_id": 1,
++                "timestamp": datetime.now(tz=timezone.utc).isoformat(),
++                "source": "user",
++                "message": instruction,
++            }
++        ]
++        # (turn, step) identifies one model call; callId maps a later `tool/result`
++        # back to the step that issued it, which is never the step it arrives in.
++        self._by_call: dict[tuple[int, int], dict[str, Any]] = {}
++        self._by_call_id: dict[str, dict[str, Any]] = {}
++        self.turn_end_reasons: list[dict[str, Any]] = []
++        self.llm_retries = 0
++
++    def _step(self, turn: Any, step: Any, timestamp: str | None) -> dict[str, Any]:
++        key = (int(turn or 0), int(step or 0))
++        if key not in self._by_call:
++            created = {
++                "step_id": len(self.steps) + 1,
++                "timestamp": timestamp,
++                "source": "agent",
++                "message": "",
++                "model_name": self.model,
++                "reasoning_effort": self.effort,
++                "llm_call_count": 1,
++            }
++            self.steps.append(created)
++            self._by_call[key] = created
++        return self._by_call[key]
++
++    def _tool_call(self, step: dict[str, Any], call_id: Any, name: Any, raw: Any) -> None:
++        if not isinstance(call_id, str) or not call_id:
++            return
++        calls = step.setdefault("tool_calls", [])
++        entry = {
++            "tool_call_id": call_id,
++            "function_name": str(name),
++            "arguments": _arguments(raw),
++        }
++        for index, existing in enumerate(calls):
++            if existing["tool_call_id"] == call_id:
++                calls[index] = entry
++                break
++        else:
++            calls.append(entry)
++        self._by_call_id[call_id] = step
++
++    def record(self, event: dict[str, Any]) -> None:
++        kind = event.get("type")
++        data = event.get("data") if isinstance(event.get("data"), dict) else {}
++        timestamp = _iso(event.get("time"))
++
++        if kind == "assistant/message":
++            step = self._step(data.get("turn"), data.get("step"), timestamp)
++            message = data.get("message") if isinstance(data.get("message"), dict) else {}
++            content = message.get("content")
++            step["message"] = _text(content, "text")
++            if reasoning := _text(content, "reasoning"):
++                step["reasoning_content"] = reasoning
++            source = message.get("source")
++            if isinstance(source, dict) and isinstance(source.get("model"), str):
++                step["model_name"] = source["model"]
++            if isinstance(data.get("usage"), dict):
++                step["metrics"] = _metrics(data["usage"])
++            if data.get("interrupted"):
++                step.setdefault("extra", {})["interrupted"] = True
++            for block in content if isinstance(content, list) else []:
++                if isinstance(block, dict) and block.get("type") == "tool-call":
++                    self._tool_call(
++                        step, block.get("id"), block.get("name"), block.get("arguments")
++                    )
++        elif kind == "tool/call":
++            step = self._step(data.get("turn"), data.get("step"), timestamp)
++            self._tool_call(
++                step, data.get("callId"), data.get("name"), data.get("arguments")
++            )
++        elif kind == "tool/result":
++            self._result(data)
++        elif kind == "turn/end":
++            reason = data.get("reason")
++            self.turn_end_reasons.append(reason if isinstance(reason, dict) else {})
++        elif kind == "llm/retry":
++            self.llm_retries += 1
++
++    def _result(self, data: dict[str, Any]) -> None:
++        message = data.get("message") if isinstance(data.get("message"), dict) else {}
++        for block in message.get("content") or []:
++            if not isinstance(block, dict) or block.get("type") != "tool-result":
++                continue
++            step = self._by_call_id.get(block.get("toolCallId"))
++            if step is None:
++                continue
++            entry: dict[str, Any] = {
++                "source_call_id": block["toolCallId"],
++                "content": _flatten(block.get("content")),
++            }
++            if block.get("isError"):
++                entry["extra"] = {"is_error": True, "error": data.get("error")}
++            results = step.setdefault("observation", {"results": []})["results"]
++            for index, existing in enumerate(results):
++                if existing["source_call_id"] == entry["source_call_id"]:
++                    results[index] = entry
++                    break
++            else:
++                results.append(entry)
++
++    def trajectory(self, finish_reason: str | None, failure: str | None) -> dict[str, Any]:
++        prompt = completion = cached = peak = 0
++        for step in self.steps:
++            metrics = step.get("metrics")
++            if not isinstance(metrics, dict):
++                continue
++            prompt += metrics["prompt_tokens"]
++            completion += metrics["completion_tokens"]
++            cached += metrics["cached_tokens"]
++            peak = max(peak, metrics["prompt_tokens"])
++        extra = {
++            "finish_reason": finish_reason,
++            "turn_end_reasons": self.turn_end_reasons,
++            "llm_retry_count": self.llm_retries,
++        }
++        if failure is not None:
++            extra["failure"] = failure
++        return {
++            "schema_version": "ATIF-v1.7",
++            "session_id": self.session,
++            "agent": {"name": "dsh-minimal", "version": _version(), "model_name": self.model},
++            "steps": self.steps,
++            "final_metrics": {
++                "total_prompt_tokens": prompt,
++                "total_completion_tokens": completion,
++                "total_cached_tokens": cached,
++                "total_steps": len(self.steps),
++                # The sdk-minimal profile has no compaction, so no summary step
++                # can replace a transcript prefix.
++                "extra": {"peak_context_tokens": peak, "summarization_count": 0},
++            },
++            "extra": extra,
++        }
++
++
++def _version() -> str:
++    try:
++        return version("deepseek-harness-sdk")
++    except PackageNotFoundError:
++        return "unknown"
++
++
++def _write(path: Path, value: Any) -> None:
++    path.parent.mkdir(parents=True, exist_ok=True)
++    temporary = path.with_suffix(f"{path.suffix}.tmp")
++    temporary.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n")
++    temporary.replace(path)
++
++
++def main() -> None:
++    parser = argparse.ArgumentParser()
++    parser.add_argument("--instruction", required=True)
++    parser.add_argument("--trajectory-path", required=True)
++    args = parser.parse_args()
++
++    # Task images can leave the agent user on a 077 umask; the session log and
++    # trajectory have to stay readable to the host user that collects /logs.
++    os.umask(0o022)
++
++    model = os.environ["DSH_MODEL"]
++    effort = os.environ.get("DSH_REASONING_EFFORT", "max")
++    session = os.environ.get("SESSION_ID") or "pier-session"
++    path = Path(args.trajectory_path)
++    collector = Collector(args.instruction, model, effort, session)
++    state: dict[str, Any] = {"finish_reason": None, "failure": None}
++
++    def checkpoint() -> None:
++        _write(path, collector.trajectory(state["finish_reason"], state["failure"]))
++
++    def on_notification(notification: Notification) -> None:
++        payload = notification.payload
++        event = payload.get("event") if isinstance(payload, dict) else None
++        if (
++            notification.method != "session.event"
++            or not isinstance(event, dict)
++            # Token deltas repeat what their `assistant/message` already carries.
++            or event.get("type") == "assistant/chunk"
++            or payload.get("sessionId") != session
++        ):
++            return
++        collector.record(event)
++        checkpoint()
++
++    checkpoint()
++    print(f"dsh-minimal: model={model} effort={effort} session={session}")
++    try:
++        with DeepSeekHarness(
++            profile="sdk-minimal",
++            provider=PROVIDER,
++            model=model,
++            reasoning_effort=effort,
++            cwd=os.getcwd(),
++            dsh_home=os.environ["DSH_HOME"],
++        ) as harness:
++            result = harness.run(
++                args.instruction, session_id=session, on_notification=on_notification
++            )
++        state["finish_reason"] = result.finish_reason
++        print(f"dsh-minimal: finish_reason={result.finish_reason}")
++        print(f"dsh-minimal: final_response={result.final_response}")
++    except Exception as error:  # noqa: BLE001 - the trajectory must survive any failure
++        state["failure"] = f"{type(error).__name__}: {error}"
++        traceback.print_exc()
++    finally:
++        checkpoint()
++
++    # `max-tokens` is a bounded model outcome the verifier can still grade; anything
++    # else non-terminal means the harness never produced a usable turn.
++    if state["failure"] is not None or state["finish_reason"] not in (
++        "completed",
++        "max-tokens",
++    ):
++        sys.exit(1)
++
++
++if __name__ == "__main__":
++    main()
+diff --git a/src/pier/agents/installed/mini_swe_agent.py b/src/pier/agents/installed/mini_swe_agent.py
+index 75d25b6..d283f66 100644
+--- a/src/pier/agents/installed/mini_swe_agent.py
++++ b/src/pier/agents/installed/mini_swe_agent.py
+@@ -11,6 +11,7 @@ from pier.agents.installed.base import (
+     BaseInstalledAgent,
+     CliFlag,
+     with_prompt_template,
++    with_runtime_constraints,
+ )
+ from pier.agents.network import allowlist_from_urls, collect_url_values
+ from pier.agents.utils import get_api_key_var_names_from_model_name
+@@ -821,7 +822,7 @@ mini-swe-agent --help
+     async def run(
+         self, instruction: str, environment: BaseEnvironment, context: AgentContext
+     ) -> None:
+-        augmented_instruction = instruction
++        augmented_instruction = with_runtime_constraints(instruction)
+         if self.mcp_servers:
+             mcp_info = "\n\nMCP Servers:\nThe following MCP servers are available for this task.\n"
+             for s in self.mcp_servers:
+diff --git a/src/pier/environments/docker/__init__.py b/src/pier/environments/docker/__init__.py
+index 4bb8f11..04a8c6e 100644
+--- a/src/pier/environments/docker/__init__.py
++++ b/src/pier/environments/docker/__init__.py
+@@ -25,6 +25,9 @@ def write_resources_compose_file(
+     *,
+     cpu_request: int | None = None,
+     cpu_limit: int | None = None,
++    environment: dict[str, str] | None = None,
++    sysctls: dict[str, str] | None = None,
++    volumes: list[str] | None = None,
+     memory_request_mb: int | None = None,
+     memory_limit_mb: int | None = None,
+ ) -> Path:
+@@ -46,7 +49,13 @@ def write_resources_compose_file(
+     if reservations:
+         resources["reservations"] = reservations
+ 
+-    main = {"deploy": {"resources": resources}} if resources else {}
++    main: dict[str, object] = {"deploy": {"resources": resources}} if resources else {}
++    if environment:
++        main["environment"] = dict(environment)
++    if sysctls:
++        main["sysctls"] = dict(sysctls)
++    if volumes:
++        main["volumes"] = list(volumes)
+     compose = {"services": {"main": main}}
+     path.parent.mkdir(parents=True, exist_ok=True)
+     path.write_text(json.dumps(compose, indent=2))
+diff --git a/src/pier/environments/docker/docker.py b/src/pier/environments/docker/docker.py
+index 2ed4e92..bc671be 100644
+--- a/src/pier/environments/docker/docker.py
++++ b/src/pier/environments/docker/docker.py
+@@ -31,6 +31,11 @@ from pier.environments.docker import (
+     write_mounts_compose_file,
+     write_resources_compose_file,
+ )
++from pier.environments.docker.parallelism import (
++    CPU_CLAMP_PATH,
++    cpu_clamp_source,
++    parallelism_env,
++)
+ from pier.models.environment_type import EnvironmentType
+ from pier.models.task.config import EnvironmentConfig, TaskOS
+ from pier.models.trial.config import ResourceMode, ServiceVolumeConfig
+@@ -102,6 +107,11 @@ class DockerEnvironment(BaseEnvironment):
+ 
+     _DOCKER_COMPOSE_WINDOWS_KEEPALIVE_PATH = COMPOSE_WINDOWS_KEEPALIVE_PATH
+ 
++    # Docker leaves IPv6 off in the container netns, so loopback has no ::1 and
++    # suites that bind it skip where a real Linux host passes. These environments
++    # always get their own netns, which is what net.* sysctls require.
++    _LINUX_SYSCTLS = {"net.ipv6.conf.all.disable_ipv6": "0"}
++
+     # Class-level lock per image name to prevent parallel builds of the same image.
+     _image_build_locks: dict[str, asyncio.Lock] = {}
+ 
+@@ -160,6 +170,7 @@ class DockerEnvironment(BaseEnvironment):
+         task_env_config: EnvironmentConfig,
+         keep_containers: bool = False,
+         mounts_json: list[ServiceVolumeConfig] | None = None,
++        mounts_override: list[ServiceVolumeConfig] | None = None,
+         *args,
+         **kwargs,
+     ):
+@@ -193,8 +204,13 @@ class DockerEnvironment(BaseEnvironment):
+             self._windows_container_name: str | None = None
+             self._platform = UnixOps(self)
+ 
++        # Configured mounts are additive so the default /logs binds survive and
++        # agent logs and artifacts stay host-visible. A separate verifier
++        # environment must not share those directories, so it overrides the set.
+         self._mounts_json = (
+-            mounts_json if mounts_json is not None else self._default_log_mounts()
++            [*self._default_log_mounts(), *(mounts_json or [])]
++            if mounts_override is None
++            else mounts_override
+         )
+         self._mounts_compose_path: Path | None = None
+         self._resources_compose_temp_dir: tempfile.TemporaryDirectory | None = None
+@@ -427,12 +443,16 @@ class DockerEnvironment(BaseEnvironment):
+             Path(self._resources_compose_temp_dir.name)
+             / f"{self.session_id}-{RESOURCES_COMPOSE_NAME}"
+         )
++        cpu_limit = self._resource_limit_value("cpu", auto_mode=ResourceMode.LIMIT)
+         return write_resources_compose_file(
+             path,
++            environment=parallelism_env(cpu_limit),
++            volumes=self._write_cpu_clamp(path.parent, cpu_limit),
++            sysctls=None if self._is_windows_container else self._LINUX_SYSCTLS,
+             cpu_request=self._resource_request_value(
+                 "cpu", auto_mode=ResourceMode.LIMIT
+             ),
+-            cpu_limit=self._resource_limit_value("cpu", auto_mode=ResourceMode.LIMIT),
++            cpu_limit=cpu_limit,
+             memory_request_mb=self._resource_request_value(
+                 "memory", auto_mode=ResourceMode.LIMIT
+             ),
+@@ -441,6 +461,15 @@ class DockerEnvironment(BaseEnvironment):
+             ),
+         )
+ 
++    def _write_cpu_clamp(self, directory: Path, cpu_limit: int | None) -> list[str]:
++        """Mount the preload that `parallelism_env` points NODE_OPTIONS at."""
++        if not cpu_limit or self._is_windows_container:
++            return []
++        source = directory / "pier-node-cpu-clamp.js"
++        source.write_text(cpu_clamp_source(cpu_limit))
++        source.chmod(0o644)
++        return [f"{source}:{CPU_CLAMP_PATH}:ro"]
++
+     def _cleanup_resources_compose_file(self) -> None:
+         if self._resources_compose_temp_dir is None:
+             return
+diff --git a/src/pier/environments/docker/parallelism.py b/src/pier/environments/docker/parallelism.py
+new file mode 100644
+index 0000000..b21ae7c
+--- /dev/null
++++ b/src/pier/environments/docker/parallelism.py
+@@ -0,0 +1,34 @@
++"""Tell test runners how many CPUs the container actually gets.
++
++Docker's ``--cpus`` is a bandwidth quota, so ``nproc`` still reports every host
++core and runner worker pools oversubscribe the container.
++"""
++
++from __future__ import annotations
++
++CPU_CLAMP_PATH = "/opt/pier-node-cpu-clamp.js"
++
++
++def cpu_clamp_source(cpus: int) -> str:
++    """A ``node --require`` preload; the Node runners take no cap from the environment."""
++    return (
++        "const os = require('node:os')\n"
++        f"const limit = {cpus}\n"
++        "const cpus = os.cpus\n"
++        "os.cpus = () => cpus.call(os).slice(0, limit)\n"
++        "os.availableParallelism = () => limit\n"
++    )
++
++
++def parallelism_env(cpus: int | None) -> dict[str, str]:
++    """Worker-count caps for the test runners, derived from the CPU limit."""
++    if not cpus or cpus < 1:
++        return {}
++    n = str(cpus)
++    return {
++        "GOMAXPROCS": n,
++        "CARGO_BUILD_JOBS": n,
++        "NEXTEST_TEST_THREADS": n,
++        "PYTEST_XDIST_AUTO_NUM_WORKERS": n,
++        "NODE_OPTIONS": f"--require {CPU_CLAMP_PATH}",
++    }
+diff --git a/src/pier/models/agent/name.py b/src/pier/models/agent/name.py
+index d84516a..41ac147 100644
+--- a/src/pier/models/agent/name.py
++++ b/src/pier/models/agent/name.py
+@@ -8,6 +8,7 @@ class AgentName(str, Enum):
+     ANTIGRAVITY_SDK = "antigravity-sdk"
+     CODEX = "codex"
+     CURSOR_CLI = "cursor-cli"
++    DSH_MINIMAL = "dsh-minimal"
+     GEMINI_CLI = "gemini-cli"
+     MINI_SWE_AGENT = "mini-swe-agent"
+     SWE_AGENT = "swe-agent"
+diff --git a/src/pier/trial/trial.py b/src/pier/trial/trial.py
+index fd5d4a2..126f0fa 100644
+--- a/src/pier/trial/trial.py
++++ b/src/pier/trial/trial.py
+@@ -402,7 +402,7 @@ class Trial:
+             trial_paths=self._trial_paths,
+             task_env_config=env_config,
+             logger=self._logger,
+-            mounts_json=self._verifier_env_mounts(env_config),
++            mounts_override=self._verifier_env_mounts(env_config),
+             agent_install_spec=None,
+             network_allowlist=None,
+             default_user=(