docs(release): document late-merged 0.10 changes before tagging

Two commits landed on main between when the 0.10 release-prep PR was
cut and when it merged, but neither updated CHANGELOG nor docs:

  - 87a3028 feat: synthetic_user_message / is_synthetic_message factories
  - b8aebc1 feat(providers): drop the "minimal" ThinkingLevel (BREAKING)

Without this patch, tagging 0.10.0 ships:
  - A BREAKING ThinkingLevel change with no CHANGELOG entry or migration
    note (anyone passing thinking="minimal" gets a silent ValidationError).
  - A documented "minimal" thinking level in the 0.10 docs snapshot
    (current/ + version-0.10/, EN + zh-Hans) that the released code
    rejects.
  - A new public synthetic-message API with no Chinese docs and no
    snapshot mention (only EN current/hooks.md was updated in 87a3028).

This commit:

  - CHANGELOG.md: adds [0.10.0] ### Removed (BREAKING) entry for the
    minimal drop with migration guidance, and ### Added entry for the
    synthetic factories.
  - website/docs + zh-Hans current/: strips "minimal" from the providers/
    anthropic and providers/overview guides (table row, code samples,
    prose enumerations).
  - website/versioned_docs/version-0.10/ + zh-Hans mirror: same strips +
    mirrors the EN hooks.md synthetic_user_message section into zh-Hans
    current/ and copies hooks.md into both snapshots.
  - website/versioned_docs/version-0.10/api/: regenerates the auto-
    generated API mdx (pnpm apiref) and copies the fresh files into the
    snapshot so it reflects the actual 0.10.0 surface — ThinkingLevel
    no longer lists "minimal", synthetic_user_message and
    is_synthetic_message appear in cubepi-providers.mdx.

Verified: diff -r current vs version-0.10 yields only the intro.mdx
Status block (expected), no "minimal" remains in any thinking-level
context, pnpm build (EN + zh-Hans) clean, vitest 4/4.

Author: xfgong

CHANGELOG.md

@@ -9,8 +9,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.10.0] - 2026-06-10
 
+### Removed (BREAKING)
+
+- **`"minimal"` removed from `ThinkingLevel`.** `ThinkingLevel` now reads
+  `Literal["off", "low", "medium", "high", "xhigh"]`; the `.minimal` field
+  is gone from `ThinkingBudgets`; `THINKING_LEVELS` no longer contains it;
+  Anthropic's default `level_budgets` and OpenAI Responses' `_THINKING_TO_EFFORT`
+  no longer map it. **Callers that previously passed `thinking="minimal"`
+  must switch to `thinking="low"` (or `"off"`).** Rationale: DeepSeek's
+  Anthropic-shape endpoint rejects `effort=minimal` on `output_config`,
+  and OpenAI's `reasoning.effort` path rewrote it to `"low"` downstream
+  anyway — keeping it was a footgun that surfaced as a 400 + fallback.
+
 ### Added
 
+- **`synthetic_user_message(text, *, source) -> UserMessage`** and
+  **`is_synthetic_message(message) -> bool`** — public marker for
+  framework-injected user-role messages. Middleware-injected nudges
+  (todo guard errors, goal continuations, compaction summaries,
+  `generate_structured` retry feedback) now stamp
+  `metadata["synthetic"] = True` so downstream UIs can tell internal
+  scaffolding apart from real human input. Real `Agent.prompt()` /
+  `Agent.steer()` messages remain unmarked. Closes #171. Exported from
+  `cubepi` and `cubepi.providers`. Use this factory (not bare
+  `UserMessage`) when returning messages from `TurnAction.inject_messages`
+  or `on_run_end`.
+
 - **`DeferredToolGroup` / `DeferredToolsMiddleware`** — progressive tool
   disclosure primitive. Hides MCP tool schemas from the model by default,
   injecting a compact catalog into the system prompt instead. The model

website/docs/guides/providers/anthropic.md

@@ -49,7 +49,6 @@ CubePi maps a `ThinkingLevel` enum onto Anthropic's `budget_tokens`:
 | Level | Default budget |
 |---|---|
 | `"off"` | thinking disabled |
-| `"minimal"` | 1024 |
 | `"low"` | 2048 |
 | `"medium"` | 8192 |
 | `"high"` | 16384 |
@@ -78,7 +77,7 @@ provider = AnthropicProvider(
         reasoning_level=ReasoningLevelSpec(
             path="thinking.budget_tokens",
             kind="int_budget",
-            level_budgets={"off": 0, "minimal": 1024, "low": 4096,
+            level_budgets={"off": 0, "low": 4096,
                            "medium": 12288, "high": 16384, "xhigh": 16384},
         ),
     ),

website/docs/guides/providers/overview.md

@@ -107,7 +107,7 @@ provider = OpenAIProvider(
 
 - `reasoning_on_payload / reasoning_off_payload` — payload merged when
   reasoning is on/off.
-- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`minimal`/... to backend
+- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`low`/... to backend
   payload paths.
 - `temperature` (`TemperatureSpec`) — clip, force, or strip temperature.
 - `max_tokens_field` — pick `max_tokens` or `max_completion_tokens`.
@@ -225,14 +225,14 @@ the capability value wins.
 ### Reasoning level: `reasoning_level` (three shapes)
 
 Beyond on/off, CubePi maps a `ThinkingLevel`
-(`off`/`minimal`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
+(`off`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
 written at a dotted `path`. `kind` picks the shape:
 
 `ReasoningLevelSpec` only changes how that level is serialized. You still need
 two call-site controls:
 
 - set `reasoning=True` when binding the model (enable reasoning for that model)
-- set the Agent's `thinking` argument to one of `off|minimal|low|medium|high|xhigh`
+- set the Agent's `thinking` argument to one of `off|low|medium|high|xhigh`
   (defaults to `off`).
 
 ```python
@@ -249,7 +249,6 @@ provider = OpenAIProvider(
             kind="effort",
             level_to_effort={
                 "off": "low",
-                "minimal": "low",
                 "low": "low",
                 "medium": "medium",
                 "high": "high",
@@ -268,15 +267,15 @@ from cubepi import ReasoningLevelSpec
 # int_budget — a token budget (Anthropic).
 ReasoningLevelSpec(
     path="thinking.budget_tokens", kind="int_budget",
-    level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+    level_budgets={"off": 0, "low": 2048,
                    "medium": 8192, "high": 16384, "xhigh": 16384},
 )
 
 # effort — an effort string (OpenAI Responses).
 ReasoningLevelSpec(
     path="reasoning.effort", kind="effort",
-    level_to_effort={"minimal": "minimal", "low": "low",
-                     "medium": "medium", "high": "high", "xhigh": "high"},
+    level_to_effort={"low": "low", "medium": "medium",
+                     "high": "high", "xhigh": "high"},
 )
 
 # enum — a vendor-specific state (Doubao's 3-state thinking).

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md

@@ -160,15 +160,22 @@ async def after_model_response(
 
 ```python
 from cubepi.middleware.base import TurnAction
-from cubepi.providers.base import UserMessage, TextContent
+from cubepi.providers.base import synthetic_user_message
 
 TurnAction(
     response=modified_message,            # 替换消息；None 则保留原消息
-    inject_messages=[UserMessage(...)],   # 在下一轮之前追加的额外消息
+    inject_messages=[                     # 在下一轮之前追加的额外消息
+        synthetic_user_message("…", source="my_middleware"),
+    ],
     decision="natural",                   # "natural" | "stop" | "loop_to_model"
 )
 ```
 
+注入的 user 角色消息**必须**用 `synthetic_user_message(text, source=...)`
+构造，不要直接 `UserMessage(...)`。工厂会写入 `metadata["synthetic"] = True`，
+下游消费者（重放历史的 UI）就能把框架插入的提示和用户真正输入的区分开来；
+`source` 是个自由格式标签，只用于 trace。判断可用 `is_synthetic_message(msg)`。
+
 三个控制流旋钮：
 
 - `decision="natural"`（默认）—— 正常进入工具执行 / 下一轮。
@@ -194,12 +201,13 @@ async def on_run_end(
     ...
 ```
 
-**每次 `prompt()` 调用结束时触发一次**——所有轮次和工具调用完成后、
-`AgentEndEvent` 发出前。返回非空 `list[Message]` 会将这些消息注入上下文
-并运行**一轮额外的模型调用**（run-end pass）。返回 `None` 或 `[]` 不做任何操作。
+**每次外层循环迭代后触发**——所有轮次和工具调用完成、循环本应退出之前。
+返回非空 `list[Message]` 会将这些消息注入上下文并继续循环（agent 再跑一次）。
+返回 `None` 或 `[]` 什么也不做（循环退出）。和 `inject_messages` 一样，
+返回的 user 角色消息要用 `synthetic_user_message(...)` 构造，让它们带上
+synthetic 标记。
 
-额外轮次只触发一次——循环内的 `_reflection_fired` 标志阻止注入轮次再次触发
-`on_run_end`。
+每次 `prompt()` 内**可以多次触发**。中间件每次返回消息，worker 就再跑一轮。
 
 **何时触发：**
 - 正常完成（所有轮次结束后循环自然 break）。

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md

@@ -46,7 +46,6 @@ CubePi 把 `ThinkingLevel` 枚举映射到 Anthropic 的 `budget_tokens`:
 | Level | 默认 budget |
 |---|---|
 | `"off"` | 关闭思考 |
-| `"minimal"` | 1024 |
 | `"low"` | 2048 |
 | `"medium"` | 8192 |
 | `"high"` | 16384 |

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md

@@ -72,7 +72,7 @@ provider = OpenAIProvider(
 
 - `reasoning_on_payload / reasoning_off_payload` — 在 reasoning 开/关时，深度
   合并到最终 payload。
-- `reasoning_level`（`ReasoningLevelSpec`）— 将 `off`/`minimal`/... 映射到后端字段。
+- `reasoning_level`（`ReasoningLevelSpec`）— 将 `off`/`low`/... 映射到后端字段。
 - `temperature`（`TemperatureSpec`）— 裁剪、固定或去掉温度参数。
 - `max_tokens_field` — 选 `max_tokens` 或 `max_completion_tokens`。
 - `supports_tools` / `supports_images` / `supports_streaming` — 供宿主应用或前端消费的能力元数据。
@@ -161,12 +161,12 @@ CapabilityDescriptor(
 
 ### 推理级别：`reasoning_level`（三种形状）
 
-在开/关之外，CubePi 将 `ThinkingLevel`（`off`/`minimal`/`low`/`medium`/`high`/`xhigh`）映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状：
+在开/关之外，CubePi 将 `ThinkingLevel`（`off`/`low`/`medium`/`high`/`xhigh`）映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状：
 
-`ReasoningLevelSpec` 只负责「`thinking`/`minimal`/`low`/... 具体映射成后端字段」；要真正生效，还要配两个参数：
+`ReasoningLevelSpec` 只负责「`thinking`/`low`/... 具体映射成后端字段」；要真正生效，还要配两个参数：
 
 - 在 `provider.model(...)` 时把 `reasoning=True`（把这个模型设为推理模型）
-- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|minimal|low|medium|high|xhigh`（默认 `off`）
+- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|low|medium|high|xhigh`（默认 `off`）
 
 ```python
 from cubepi import Agent, CapabilityDescriptor, ReasoningLevelSpec
@@ -181,7 +181,6 @@ provider = OpenAIProvider(
             kind="effort",
             level_to_effort={
                 "off": "low",
-                "minimal": "low",
                 "low": "low",
                 "medium": "medium",
                 "high": "high",
@@ -200,15 +199,15 @@ from cubepi import ReasoningLevelSpec
 # int_budget — a token budget (Anthropic).
 ReasoningLevelSpec(
     path="thinking.budget_tokens", kind="int_budget",
-    level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+    level_budgets={"off": 0, "low": 2048,
                    "medium": 8192, "high": 16384, "xhigh": 16384},
 )
 
 # effort — an effort string (OpenAI Responses).
 ReasoningLevelSpec(
     path="reasoning.effort", kind="effort",
-    level_to_effort={"minimal": "minimal", "low": "low",
-                     "medium": "medium", "high": "high", "xhigh": "high"},
+    level_to_effort={"low": "low", "medium": "medium",
+                     "high": "high", "xhigh": "high"},
 )
 
 # enum — a vendor-specific state (Doubao's 3-state thinking).

website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md

@@ -160,15 +160,22 @@ async def after_model_response(
 
 ```python
 from cubepi.middleware.base import TurnAction
-from cubepi.providers.base import UserMessage, TextContent
+from cubepi.providers.base import synthetic_user_message
 
 TurnAction(
     response=modified_message,            # 替换消息；None 则保留原消息
-    inject_messages=[UserMessage(...)],   # 在下一轮之前追加的额外消息
+    inject_messages=[                     # 在下一轮之前追加的额外消息
+        synthetic_user_message("…", source="my_middleware"),
+    ],
     decision="natural",                   # "natural" | "stop" | "loop_to_model"
 )
 ```
 
+注入的 user 角色消息**必须**用 `synthetic_user_message(text, source=...)`
+构造，不要直接 `UserMessage(...)`。工厂会写入 `metadata["synthetic"] = True`，
+下游消费者（重放历史的 UI）就能把框架插入的提示和用户真正输入的区分开来；
+`source` 是个自由格式标签，只用于 trace。判断可用 `is_synthetic_message(msg)`。
+
 三个控制流旋钮：
 
 - `decision="natural"`（默认）—— 正常进入工具执行 / 下一轮。
@@ -194,12 +201,13 @@ async def on_run_end(
     ...
 ```
 
-**每次 `prompt()` 调用结束时触发一次**——所有轮次和工具调用完成后、
-`AgentEndEvent` 发出前。返回非空 `list[Message]` 会将这些消息注入上下文
-并运行**一轮额外的模型调用**（run-end pass）。返回 `None` 或 `[]` 不做任何操作。
+**每次外层循环迭代后触发**——所有轮次和工具调用完成、循环本应退出之前。
+返回非空 `list[Message]` 会将这些消息注入上下文并继续循环（agent 再跑一次）。
+返回 `None` 或 `[]` 什么也不做（循环退出）。和 `inject_messages` 一样，
+返回的 user 角色消息要用 `synthetic_user_message(...)` 构造，让它们带上
+synthetic 标记。
 
-额外轮次只触发一次——循环内的 `_reflection_fired` 标志阻止注入轮次再次触发
-`on_run_end`。
+每次 `prompt()` 内**可以多次触发**。中间件每次返回消息，worker 就再跑一轮。
 
 **何时触发：**
 - 正常完成（所有轮次结束后循环自然 break）。

website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md

@@ -46,7 +46,6 @@ CubePi 把 `ThinkingLevel` 枚举映射到 Anthropic 的 `budget_tokens`:
 | Level | 默认 budget |
 |---|---|
 | `"off"` | 关闭思考 |
-| `"minimal"` | 1024 |
 | `"low"` | 2048 |
 | `"medium"` | 8192 |
 | `"high"` | 16384 |

website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md

@@ -72,7 +72,7 @@ provider = OpenAIProvider(
 
 - `reasoning_on_payload / reasoning_off_payload` — 在 reasoning 开/关时，深度
   合并到最终 payload。
-- `reasoning_level`（`ReasoningLevelSpec`）— 将 `off`/`minimal`/... 映射到后端字段。
+- `reasoning_level`（`ReasoningLevelSpec`）— 将 `off`/`low`/... 映射到后端字段。
 - `temperature`（`TemperatureSpec`）— 裁剪、固定或去掉温度参数。
 - `max_tokens_field` — 选 `max_tokens` 或 `max_completion_tokens`。
 - `supports_tools` / `supports_images` / `supports_streaming` — 供宿主应用或前端消费的能力元数据。
@@ -161,12 +161,12 @@ CapabilityDescriptor(
 
 ### 推理级别：`reasoning_level`（三种形状）
 
-在开/关之外，CubePi 将 `ThinkingLevel`（`off`/`minimal`/`low`/`medium`/`high`/`xhigh`）映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状：
+在开/关之外，CubePi 将 `ThinkingLevel`（`off`/`low`/`medium`/`high`/`xhigh`）映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状：
 
-`ReasoningLevelSpec` 只负责「`thinking`/`minimal`/`low`/... 具体映射成后端字段」；要真正生效，还要配两个参数：
+`ReasoningLevelSpec` 只负责「`thinking`/`low`/... 具体映射成后端字段」；要真正生效，还要配两个参数：
 
 - 在 `provider.model(...)` 时把 `reasoning=True`（把这个模型设为推理模型）
-- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|minimal|low|medium|high|xhigh`（默认 `off`）
+- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|low|medium|high|xhigh`（默认 `off`）
 
 ```python
 from cubepi import Agent, CapabilityDescriptor, ReasoningLevelSpec
@@ -181,7 +181,6 @@ provider = OpenAIProvider(
             kind="effort",
             level_to_effort={
                 "off": "low",
-                "minimal": "low",
                 "low": "low",
                 "medium": "medium",
                 "high": "high",
@@ -200,15 +199,15 @@ from cubepi import ReasoningLevelSpec
 # int_budget — a token budget (Anthropic).
 ReasoningLevelSpec(
     path="thinking.budget_tokens", kind="int_budget",
-    level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+    level_budgets={"off": 0, "low": 2048,
                    "medium": 8192, "high": 16384, "xhigh": 16384},
 )
 
 # effort — an effort string (OpenAI Responses).
 ReasoningLevelSpec(
     path="reasoning.effort", kind="effort",
-    level_to_effort={"minimal": "minimal", "low": "low",
-                     "medium": "medium", "high": "high", "xhigh": "high"},
+    level_to_effort={"low": "low", "medium": "medium",
+                     "high": "high", "xhigh": "high"},
 )
 
 # enum — a vendor-specific state (Doubao's 3-state thinking).