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: count resolve_tool_call everywhere hooks are enumerated (8 -> 9)
xf gongecfb98a1a71f
diff --git a/README.md b/README.mdindex d19079b..0e14cdb 100644--- a/README.md+++ b/README.md@@ -182,6 +182,7 @@ hooks = compose_middleware([LoggingMiddleware(), SafetyMiddleware()])|------|------|| `transform_context` | Chained — each receives previous result || `convert_to_llm` | Last implementation wins |+| `resolve_tool_call` | First non-`None` rewrite wins (short-circuits) || `before_tool_call` | Any block stops execution || `after_tool_call` | Later overrides earlier || `transform_system_prompt` | Chained — each receives previous result |diff --git a/website/docs/getting-started/core-concepts.md b/website/docs/getting-started/core-concepts.mdindex 0ef986e..dfb8083 100644--- a/website/docs/getting-started/core-concepts.md+++ b/website/docs/getting-started/core-concepts.md@@ -121,13 +121,14 @@ Subscribe to agent events for UI; for low-level token routing dig into## Middleware-`Middleware` is a class with up to eight typed hooks:+`Middleware` is a class with up to nine typed hooks:| Hook | When it runs | Composition rule ||---|---|---|| `transform_context` | Before each model call, on the message list | Chained — each receives previous result || `convert_to_llm` | Right before serialisation to the provider | Last implementation wins || `transform_system_prompt` | Before each model call, on the system prompt | Chained |+| `resolve_tool_call` | Per tool call, before validation — may rewrite the call | First non-`None` wins || `before_tool_call` | Per tool call, after arg validation | First `block=True` short-circuits || `after_tool_call` | Per tool call, after `execute` | Later override earlier || `after_model_response` | After the assistant message lands | Returns a `TurnAction` controlling flow |diff --git a/website/docs/guides/middleware/composition.md b/website/docs/guides/middleware/composition.mdindex d9ed7d0..1246611 100644--- a/website/docs/guides/middleware/composition.md+++ b/website/docs/guides/middleware/composition.md@@ -18,6 +18,7 @@ to remember "before" or "after" precedence guesses.| `transform_context` | **Chain** — each sees previous output | Yes || `convert_to_llm` | **Last wins** | Only the last one runs || `transform_system_prompt` | **Chain** | Yes |+| `resolve_tool_call` | **First non-`None` wins** — rewrites the call before validation | First match short-circuits || `before_tool_call` | **First block stops**; non-block accumulates | Block wins; `edited_args` last-writer-wins; `hitl_trace` merges || `after_tool_call` | **Later overrides earlier** | Last write wins || `should_stop_after_turn` | **Any `True` stops** (OR) | No |@@ -53,6 +54,18 @@ If you find yourself needing two `convert_to_llm` middlewares,collapse them into one (call site composition: write one that callsboth).+## `resolve_tool_call`++**First non-`None` wins.** The first middleware to return a rewritten+`ToolCall` short-circuits the chain — later resolvers never see the+original call, and no resolver ever sees another resolver's output. If+every middleware returns `None`, the call proceeds unchanged.++This deliberately differs from `before_tool_call`'s chaining: a+resolution is a single rewrite (e.g. unwrapping the+[deferred-tools](./deferred-tools) dispatcher to the real tool), not an+accumulation.+## `before_tool_call`First `block=True` short-circuits the rest. **Non-block returnsdiff --git a/website/docs/intro.mdx b/website/docs/intro.mdxindex d092a68..11829a9 100644--- a/website/docs/intro.mdx+++ b/website/docs/intro.mdx@@ -35,10 +35,10 @@ working tool-using agent in under five minutes.conversation length — SQLite for laptops, Postgres for production.- **Native multi-provider.** Anthropic and OpenAI ship in the box,through a `Provider` Protocol. Add a new provider in one class.-- **Eight-hook middleware.** `transform_context`, `convert_to_llm`,- `transform_system_prompt`, `before_tool_call`, `after_tool_call`,- `should_stop_after_turn`, `after_model_response`, `on_run_end` — each- with explicit composition rules. No mystery node ordering.+- **Nine-hook middleware.** `transform_context`, `convert_to_llm`,+ `transform_system_prompt`, `resolve_tool_call`, `before_tool_call`,+ `after_tool_call`, `should_stop_after_turn`, `after_model_response`,+ `on_run_end` — each with explicit composition rules. No mystery node ordering.- **MCP loaders.** Point at any[Model Context Protocol](https://modelcontextprotocol.io) server(HTTP or stdio) and get back a list of `AgentTool`s.diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.mdindex 3906943..cbaadb5 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/core-concepts.md@@ -97,13 +97,14 @@ class Provider(Protocol):## Middleware-`Middleware` 是有最多八个类型化 hook 的类:+`Middleware` 是有最多九个类型化 hook 的类:| Hook | 何时触发 | 组合规则 ||---|---|---|| `transform_context` | 每次调模型之前,处理消息列表 | 链式 —— 每个收到上一个的输出 || `convert_to_llm` | provider 序列化之前 | 最后一个实现生效 || `transform_system_prompt` | 每次调模型之前,处理 system prompt | 链式 |+| `resolve_tool_call` | 每个工具调用之前(参数校验之前,可改写调用) | 第一个非 `None` 胜出 || `before_tool_call` | 每个工具调用之前(在参数校验后) | 第一个 `block=True` 短路 || `after_tool_call` | 每个工具调用之后(在 `execute` 之后) | 后写覆盖先写 || `after_model_response` | assistant 消息落定之后 | 返回 `TurnAction` 控制流向 |diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.mdindex 8e746a4..5aa2653 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/composition.md@@ -16,6 +16,7 @@ description: "了解 CubePi 如何通过 per-hook 规则组合多个中间件。| `transform_context` | **链式**——每个看到上一个的输出 | 是 || `convert_to_llm` | **最后一个胜出** | 只有一个运行 || `transform_system_prompt` | **链式** | 是 |+| `resolve_tool_call` | **第一个非 `None` 胜出**——在校验前改写调用 | 第一个命中即短路 || `before_tool_call` | **第一个 block 停止**;非 block 累积 | block 胜出;`edited_args` 最后写入者胜出;`hitl_trace` 合并 || `after_tool_call` | **后面覆盖前面** | 最后写入胜出 || `should_stop_after_turn` | **任一 True 即停止**(OR) | 否 |@@ -46,6 +47,16 @@ CubePi 强制**列表中的最后一个**实现了 `convert_to_llm` 的中间件如果你发现自己需要两个 `convert_to_llm` 中间件,将它们合并为一个(调用点组合:写一个调用两者的中间件)。+## `resolve_tool_call`++**第一个非 `None` 返回值胜出。** 第一个返回改写后 `ToolCall` 的中间件+会短路整个链——后面的 resolver 看不到原始调用,任何 resolver 也看不到+其他 resolver 的输出。全部返回 `None` 时调用原样继续。++这与 `before_tool_call` 的链式组合是刻意不同的:一次 resolution 是+单一改写(例如把[延迟工具](./deferred-tools)的 dispatcher 解包成+真实工具),不是累积。+## `before_tool_call`第一个 `block=True` 短路其余中间件。**非 block 返回累积:**diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdxindex 9695b49..d92e3a2 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx@@ -35,10 +35,10 @@ pip install cubepi生产环境。- **原生多 provider。** Anthropic 和 OpenAI 开箱即用,通过 `Provider`Protocol 接入。要新增一个 provider 只需要写一个类。-- **八个 Hook 的中间件。** `transform_context`、`convert_to_llm`、- `transform_system_prompt`、`before_tool_call`、`after_tool_call`、- `should_stop_after_turn`、`after_model_response`、`on_run_end`——- 每一个都有明确的组合规则。没有"节点执行顺序之谜"。+- **九个 Hook 的中间件。** `transform_context`、`convert_to_llm`、+ `transform_system_prompt`、`resolve_tool_call`、`before_tool_call`、+ `after_tool_call`、`should_stop_after_turn`、`after_model_response`、+ `on_run_end`——每一个都有明确的组合规则。没有"节点执行顺序之谜"。- **MCP 加载器。** 指向任意[Model Context Protocol](https://modelcontextprotocol.io) 服务器(HTTP 或 stdio),就能拿回一组 `AgentTool`。