CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
docs(release): document late-merged 0.10 changes before tagging
xf gongf46ac66c145d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b368e9e..fb27242 100644--- a/CHANGELOG.md+++ b/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 tooldisclosure primitive. Hides MCP tool schemas from the model by default,injecting a compact catalog into the system prompt instead. The modeldiff --git a/website/docs/guides/providers/anthropic.md b/website/docs/guides/providers/anthropic.mdindex c1f4acc..cbf5878 100644--- a/website/docs/guides/providers/anthropic.md+++ b/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},),),diff --git a/website/docs/guides/providers/overview.md b/website/docs/guides/providers/overview.mdindex 476b24e..920f96b 100644--- a/website/docs/guides/providers/overview.md+++ b/website/docs/guides/providers/overview.md@@ -107,7 +107,7 @@ provider = OpenAIProvider(- `reasoning_on_payload / reasoning_off_payload` — payload merged whenreasoning is on/off.-- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`minimal`/... to backend+- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`low`/... to backendpayload 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 valuewritten at a dotted `path`. `kind` picks the shape:`ReasoningLevelSpec` only changes how that level is serialized. You still needtwo 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).diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.mdindex a30d06c..d2265c9 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md@@ -160,15 +160,22 @@ async def after_model_response(```pythonfrom cubepi.middleware.base import TurnAction-from cubepi.providers.base import UserMessage, TextContent+from cubepi.providers.base import synthetic_user_messageTurnAction(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)。diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.mdindex ff7b846..c493b22 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md+++ b/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 |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.mdindex 37193ee..5537541 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md+++ b/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`)```pythonfrom 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).diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.mdindex a30d06c..d2265c9 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md@@ -160,15 +160,22 @@ async def after_model_response(```pythonfrom cubepi.middleware.base import TurnAction-from cubepi.providers.base import UserMessage, TextContent+from cubepi.providers.base import synthetic_user_messageTurnAction(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)。diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.mdindex ff7b846..c493b22 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md+++ b/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 |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.mdindex 37193ee..5537541 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md+++ b/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`)```pythonfrom 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).diff --git a/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx b/website/versioned_docs/version-0.10/api/cubepi-middleware.mdxindex a8fa20c..2617281 100644--- a/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx+++ b/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx@@ -232,7 +232,7 @@ GoalMiddleware(self, evaluator: BoundModel, max_evaluations: int = 10)```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L72)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L73)**Methods**@@ -243,7 +243,7 @@ GoalMiddleware(self, evaluator: BoundModel, max_evaluations: int = 10)extra_llm_calls() -> Iterable[BoundModel]```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L83)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L84)#### `transform_context` {#goalmiddleware-transform-context}@@ -252,7 +252,7 @@ extra_llm_calls() -> Iterable[BoundModel]transform_context(messages: list[Message], *, ctx: AgentContext, signal: asyncio.Event | None = None) -> list[Message]```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L86)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L87)#### `on_run_end` {#goalmiddleware-on-run-end}@@ -261,7 +261,7 @@ transform_context(messages: list[Message], *, ctx: AgentContext, signal: asyncioon_run_end(ctx: AgentContext, *, signal: asyncio.Event | None = None) -> list[Message] | None```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L121)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L122)@@ -350,7 +350,7 @@ _class_A single todo item with content and status.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L131)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L132)**Attributes**@@ -365,7 +365,7 @@ _class_A guard escalation payload carried across the forced end turn.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L148)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L149)**Attributes**@@ -435,7 +435,7 @@ Hooks:* finalization hard guard → loop_to_model with correction message* otherwise → return None (natural flow)-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L465)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L466)**Attributes**@@ -453,7 +453,7 @@ transform_system_prompt(system_prompt: str, *, ctx: AgentContext, signal: asynciAppend the write_todos system instructions.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L507)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L508)#### `transform_context` {#todolistmiddleware-transform-context}@@ -470,7 +470,7 @@ context to ensure the model always sees the current todo list.When no todos are set, messages are returned unchanged (no injection).-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L522)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L523)#### `after_tool_call` {#todolistmiddleware-after-tool-call}@@ -489,7 +489,7 @@ in extra["_todos_snapshot"]. Each duplicate write_todos call's result isreplaced with an error here, and extra["todos"] is restored to the snapshotso the turn leaves the checklist unchanged.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L556)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L557)#### `after_model_response` {#todolistmiddleware-after-model-response}@@ -504,7 +504,7 @@ Inspects the latest assistant message, transitions the blocked /stale-iteration state stored in `extra`, and returns a`TurnAction` when the loop needs an injected nudge or hard stop.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L647)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L653)@@ -514,7 +514,7 @@ _class_Input schema for the `write_todos` tool.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L261)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L262)**Attributes**diff --git a/website/versioned_docs/version-0.10/api/cubepi-providers.mdx b/website/versioned_docs/version-0.10/api/cubepi-providers.mdxindex fb77d97..641c133 100644--- a/website/versioned_docs/version-0.10/api/cubepi-providers.mdx+++ b/website/versioned_docs/version-0.10/api/cubepi-providers.mdx@@ -56,7 +56,7 @@ Per-call mutators (`StreamOptions.on_payload`,semantics and fire independently of the persistent listener registrybelow.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L611)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L639)**Attributes**@@ -72,7 +72,7 @@ below.model(id: str, *, api: str = '', reasoning: bool = False, context_window: int = 200000, max_tokens: int = 8192, temperature: float = 0.7, cost: ModelCost | None = None, thinking_level_map: dict[str, str | None] | None = None) -> BoundModel```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L637)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L665)#### `stream` {#baseprovider-stream}@@ -81,7 +81,7 @@ model(id: str, *, api: str = '', reasoning: bool = False, context_window: int =stream(model: Model, messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L664)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L692)#### `generate` {#baseprovider-generate}@@ -92,7 +92,7 @@ generate(model: Model, messages: list[Message], *, system_prompt: str = '', toolRun a single provider call and return the final assistant message.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L676)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L704)#### `subscribe_request` {#baseprovider-subscribe-request}@@ -105,7 +105,7 @@ Register a persistent observer for request payloads.Returns a detach callable that removes this specific subscription.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L729)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L757)#### `subscribe_chunk` {#baseprovider-subscribe-chunk}@@ -118,7 +118,7 @@ Register a persistent observer for stream chunks.Returns a detach callable.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L737)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L765)#### `subscribe_response` {#baseprovider-subscribe-response}@@ -131,7 +131,7 @@ Register a persistent observer for assembled responses.Returns a detach callable.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L745)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L773)@@ -144,7 +144,7 @@ BoundModel(self, provider: Provider, spec: Model)```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L779)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L807)**Attributes**@@ -161,7 +161,7 @@ BoundModel(self, provider: Provider, spec: Model)stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L784)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L812)#### `generate` {#boundmodel-generate}@@ -170,7 +170,7 @@ stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefigenerate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None, max_output_tokens: int | None = None, temperature: float | None = None, thinking: ThinkingLevel | None = None, thinking_budgets: ThinkingBudgets | None = None) -> AssistantMessage```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L808)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L836)#### `generate_structured` {#boundmodel-generate-structured}@@ -179,7 +179,7 @@ generate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDegenerate_structured(output_type: type[BaseModelT], messages: list[Message], *, system_prompt: str = '', tool_name: str = 'structured_output', tool_description: str = 'Return the structured output', max_output_tokens: int | None = None, temperature: float | None = None, max_retries: int = 1) -> BaseModelT```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L835)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L863)@@ -231,7 +231,7 @@ MessageStream(self)```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L223)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L260)**Methods**@@ -242,7 +242,7 @@ MessageStream(self)attach_task(task: asyncio.Task) -> None```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L231)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L268)#### `push` {#messagestream-push}@@ -251,7 +251,7 @@ attach_task(task: asyncio.Task) -> Nonepush(event: StreamEvent) -> None```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L243)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L280)#### `set_result` {#messagestream-set-result}@@ -260,7 +260,7 @@ push(event: StreamEvent) -> Noneset_result(message: AssistantMessage) -> None```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L248)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L285)#### `result` {#messagestream-result}@@ -279,7 +279,7 @@ teardown could exit before async response listeners have run.Producer exceptions are NOT re-raised here; they were alreadysurfaced via the result future or the stream's error events.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L261)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L298)@@ -333,7 +333,7 @@ Persistent observer. Fires for every StreamEvent pushed onto the streamHeavy listeners should early-return on irrelevant event types — this hookfires hot. Return value is ignored.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L315)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L352)### OnPayloadCallback {#onpayloadcallback}@@ -347,7 +347,7 @@ OnPayloadCallback = Callable[[dict, Model], Awaitable[dict | None] | dict | NoneOptional callback for inspecting/replacing provider payloads before sending.Return a dict to replace the payload, or None to keep unchanged.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L302)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L339)### OnRequestCallback {#onrequestcallback}@@ -362,7 +362,7 @@ Persistent observer. Fires just before HTTP send, after any per-call`StreamOptions.on_payload` mutation has been applied. Receives the finalwire payload dict and the Model. Return value is ignored.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L310)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L347)### OnResponseBodyCallback {#onresponsebodycallback}@@ -383,7 +383,7 @@ finally block, after the stream terminates.`asyncio.CancelledError`), or None on normal completion.Return value is ignored.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L321)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L358)### OnResponseCallback {#onresponsecallback}@@ -396,7 +396,7 @@ OnResponseCallback = Callable[['ProviderResponse', Model], Awaitable[None] | NonOptional callback invoked after an HTTP response is received.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L306)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L343)### Provider {#provider}@@ -404,7 +404,7 @@ Optional callback invoked after an HTTP response is received._class_-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L582)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L610)**Methods**@@ -415,7 +415,7 @@ _class_stream(model: Model, messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L584)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L612)#### `generate` {#provider-generate}@@ -424,7 +424,7 @@ stream(model: Model, messages: list[Message], *, system_prompt: str = '', tools:generate(model: Model, messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None, max_output_tokens: int | None = None, temperature: float | None = None, thinking: ThinkingLevel | None = None, thinking_budgets: ThinkingBudgets | None = None) -> AssistantMessage```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L595)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L623)@@ -438,7 +438,7 @@ ProviderResponse(self, status: int, headers: dict[str, str] = dict())HTTP response metadata exposed to on_response callbacks.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L294)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L331)**Attributes**@@ -452,7 +452,7 @@ HTTP response metadata exposed to on_response callbacks._class_-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L171)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L208)**Attributes**@@ -470,7 +470,7 @@ _class_Options bag for Provider.stream(), transparent to the agent loop.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L543)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L571)**Attributes**@@ -503,12 +503,11 @@ _class_Token budgets for each thinking level.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L29)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L30)**Attributes**-- `minimal`: `int`- `low`: `int`- `medium`: `int`- `high`: `int`@@ -533,11 +532,11 @@ _class__attribute_```python-ThinkingLevel = Literal['off', 'minimal', 'low', 'medium', 'high', 'xhigh']+ThinkingLevel = Literal['off', 'low', 'medium', 'high', 'xhigh']```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L24)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L25)### ToolCall {#toolcall}@@ -561,7 +560,7 @@ _class__class_-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L165)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L202)**Attributes**@@ -625,6 +624,38 @@ _class_- `run_id`: `str | None`+### is_synthetic_message {#is-synthetic-message}++_function_++```python+is_synthetic_message(message: Message) -> bool+```++True if `message` was injected by the framework rather than a human.++[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L197)+++### synthetic_user_message {#synthetic-user-message}++_function_++```python+synthetic_user_message(text: str, *, source: str) -> UserMessage+```++Build a user-role message injected by the framework, not typed by a human.++All injected user-role messages MUST be created through this factory so+downstream consumers can branch on a single marker+(`metadata["synthetic"] is True`). `source` (e.g. `"todo_guard"`,+`"goal_continuation"`) is for tracing/debugging only — UI behavior+should never depend on it.++[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L179)++### adjust_max_tokens_for_thinking {#adjust-max-tokens-for-thinking}_function_@@ -680,7 +711,7 @@ Used by `cubepi.tracing.recorder.Recorder.attach` andfallback chain so post-failover provider events land in the trace /metric stream.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L907)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L937)### collect_agent_providers {#collect-agent-providers}@@ -699,7 +730,7 @@ by both `cubepi.tracing.recorder.Recorder.attach` and`cubepi.tracing.meter.Meter.attach` to dedupe the prelude thatfinds providers to subscribe to.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L960)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L988)### FauxProvider {#fauxprovider}@@ -819,7 +850,7 @@ DEFAULT_TRIGGER_ERRORS: frozenset[type[ProviderError]] = frozenset({RateLimited,```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L40)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L36)### FallbackBoundModel {#fallbackboundmodel}@@ -847,7 +878,7 @@ chain (via chain_providers() below), so post-failover chat spans andprovider metrics land in the trace / metric stream like primary-legcalls do.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L45)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L41)**Attributes**@@ -867,7 +898,7 @@ calls do.stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L124)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L120)#### `generate` {#fallbackboundmodel-generate}@@ -876,7 +907,7 @@ stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefigenerate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None, max_output_tokens: int | None = None, temperature: float | None = None, thinking: ThinkingLevel | None = None, thinking_budgets: ThinkingBudgets | None = None) -> AssistantMessage```-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L200)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L196)@@ -885,7 +916,7 @@ generate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDe_attribute_```python-THINKING_LEVELS: list[ThinkingLevel] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh']+THINKING_LEVELS: list[ThinkingLevel] = ['off', 'low', 'medium', 'high', 'xhigh']```@@ -906,7 +937,7 @@ If *level* is already supported, return it unchanged. Otherwise searchupward first (higher intensity), then downward, through the ordered levellist to find the closest available level.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L54)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L53)### get_supported_thinking_levels {#get-supported-thinking-levels}@@ -925,7 +956,7 @@ Return the thinking levels supported by *model*.`"xhigh"` is only included when it has an explicit (non-None) mapping.All other levels are included by default when the map omits them.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L22)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L21)### models_are_equal {#models-are-equal}@@ -941,7 +972,7 @@ Return `True` if *a* and *b* refer to the same model.Comparison is by `id` and `provider_id`. Returns `False` when eitherargument is `None`.-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L87)+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L86)diff --git a/website/versioned_docs/version-0.10/guides/middleware/hooks.md b/website/versioned_docs/version-0.10/guides/middleware/hooks.mdindex cf49486..bde1e27 100644--- a/website/versioned_docs/version-0.10/guides/middleware/hooks.md+++ b/website/versioned_docs/version-0.10/guides/middleware/hooks.md@@ -170,15 +170,24 @@ hook returns a `TurnAction`:```pythonfrom cubepi.middleware.base import TurnAction-from cubepi.providers.base import UserMessage, TextContent+from cubepi.providers.base import synthetic_user_messageTurnAction(response=modified_message, # replace the message; None to keep- inject_messages=[UserMessage(...)], # extra messages to append before next turn+ inject_messages=[ # extra messages to append before next turn+ synthetic_user_message("…", source="my_middleware"),+ ],decision="natural", # "natural" | "stop" | "loop_to_model")```+Injected user-role messages **must** be built with+`synthetic_user_message(text, source=...)`, never with a bare+`UserMessage`. The factory stamps `metadata["synthetic"] = True` so+downstream consumers (UIs replaying history) can tell framework nudges+apart from messages the human actually typed; `source` is a free-form+tag for traces only. Check with `is_synthetic_message(msg)`.+Three control-flow knobs:- `decision="natural"` (default) — proceed to tool execution / next@@ -211,7 +220,9 @@ Fires **after each outer-loop iteration** — i.e. after all turns andtool calls complete before the loop would normally exit. Return anon-empty `list[Message]` to inject those messages into context andcontinue the loop (the agent runs again). Return `None` or `[]` to do-nothing (the loop exits).+nothing (the loop exits). As with `inject_messages`, build returned+user-role messages with `synthetic_user_message(...)` so they carry+the synthetic marker.This hook can fire **multiple times** per `prompt()` call. Each timethe middleware returns messages, the worker gets another run. Returndiff --git a/website/versioned_docs/version-0.10/guides/providers/anthropic.md b/website/versioned_docs/version-0.10/guides/providers/anthropic.mdindex c1f4acc..cbf5878 100644--- a/website/versioned_docs/version-0.10/guides/providers/anthropic.md+++ b/website/versioned_docs/version-0.10/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},),),diff --git a/website/versioned_docs/version-0.10/guides/providers/overview.md b/website/versioned_docs/version-0.10/guides/providers/overview.mdindex 476b24e..920f96b 100644--- a/website/versioned_docs/version-0.10/guides/providers/overview.md+++ b/website/versioned_docs/version-0.10/guides/providers/overview.md@@ -107,7 +107,7 @@ provider = OpenAIProvider(- `reasoning_on_payload / reasoning_off_payload` — payload merged whenreasoning is on/off.-- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`minimal`/... to backend+- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`low`/... to backendpayload 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 valuewritten at a dotted `path`. `kind` picks the shape:`ReasoningLevelSpec` only changes how that level is serialized. You still needtwo 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).