Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
JavaScript agentagentsai-agentdeepagentsdesignhyperframeslanggraphmanaged-agentsmotion-graphicspaperslackvideo
Keep native features on the LangSmith Gateway; port the latest-turn history rules
Amal Irgashev16571416f64d
diff --git a/docs/cli.md b/docs/cli.mdindex 92cdbb9..17dfb2b 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -13,7 +13,7 @@| `sandbox build\|test\|publish\|use SNAPSHOT` | build the local image, run its probe, publish the LangSmith snapshot for MDA, point local runs at a snapshot || `skills verify\|sync-vendor` | vendored HyperFrames skills against `skills-lock.json`; re-vendor from upstream || `manifest` | what the workspace stager puts in each sandbox |-| `deploy [--build-only] [--yes]` | preflight, stage what ships, `mda deploy` after a yes ([MDA](deploy-mda.md)) |+| `deploy [--build-only] [--yes] [--name NAME]` | preflight, stage what ships, `mda deploy` after a yes; `--name` makes a separate deployment ([MDA](deploy-mda.md)) || `dev` | the staged project in `mda dev` (LangSmith Studio) || `serve` | the self-hosted HTTP API ([self-hosting](self-hosting.md)) || `slack` | the self-hosted Slack app |diff --git a/docs/models.md b/docs/models.mdindex 7b15b50..91a2804 100644--- a/docs/models.md+++ b/docs/models.md@@ -10,8 +10,9 @@ ANTHROPIC_API_KEY=…`provider:model` is LangChain's `init_chat_model` form. Anthropic and OpenAI are installed bydefault; Google, Groq and Mistral are extras (`uv sync --extra google`). The LangSmith Gateway is an-optional preset (`langsmith:anthropic/claude-opus-5-5` with `LANGSMITH_GATEWAY_API_KEY`), never-required. For an OpenAI-compatible endpoint, set `DESIGN_AGENT_MODEL_BASE_URL` and+optional preset (`langsmith:anthropic/claude-opus-5-5` with `LANGSMITH_GATEWAY_API_KEY`, else+`LANGSMITH_API_KEY`), never required. Anthropic and OpenAI models go through the gateway's native+routes and keep every feature in the table below; other providers use its shared route. For an OpenAI-compatible endpoint, set `DESIGN_AGENT_MODEL_BASE_URL` and`DESIGN_AGENT_MODEL_API_KEY_ENV` (the name of the variable that holds its key).## Roles@@ -39,7 +40,7 @@ runs on the portable path (all features that do not depend on the provider).| `anthropic:claude-haiku-5-5` | provider tool search | no effort parameter; good for `look` and the selector || `openai:gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-sol` | provider tool search | Responses API; reasoning effort || `google_genai:gemini-3.6-flash` | bounded selector | no provider-side tool search |-| anything else, a gateway or a base URL | bounded selector | no provider-feature claims |+| anything else, the gateway's shared route, or a base URL | bounded selector | no provider-feature claims |Adding a model: add an entry with the facts from the provider's current documentation, a test in`tests/unit/test_config_and_registry.py`, and run the eval set (`docs/evals.md`) before relying on it.diff --git a/src/design_agent/cli.py b/src/design_agent/cli.pyindex f219819..bdfe589 100644--- a/src/design_agent/cli.py+++ b/src/design_agent/cli.py@@ -217,12 +217,24 @@ def brand_show() -> None:is_flag=True,help="Deploy on the Docker image base (1 GiB filesystem: development only).",)-def deploy(yes: bool, build_only: bool, allow_docker_base: bool) -> None:+ "--name",+ default="design-agent",+ show_default=True,+ help="Deployment name; a second name is a separate deployment (for example a test one).",+)+def deploy(yes: bool, build_only: bool, allow_docker_base: bool, name: str) -> None:"""Preflight, stage only what ships, then `mda deploy` to your LangSmith workspace."""from design_agent.deploy import deploy_mainsys.exit(- deploy_main(_root(), yes=yes, build_only=build_only, allow_docker_base=allow_docker_base)+ deploy_main(+ _root(),+ yes=yes,+ build_only=build_only,+ allow_docker_base=allow_docker_base,+ name=name,+ ))diff --git a/src/design_agent/deploy.py b/src/design_agent/deploy.pyindex 1d4f13e..32e49d3 100644--- a/src/design_agent/deploy.py+++ b/src/design_agent/deploy.py@@ -206,6 +206,7 @@ def deploy_main(yes: bool = False,build_only: bool = False,allow_docker_base: bool = False,+ name: str = "design-agent",confirm: Callable[[str], bool] | None = None,run: Callable[[list[str], dict[str, str]], int] | None = None,) -> int:@@ -235,12 +236,12 @@ def deploy_main(local = dotenv_values(env_file) if env_file.is_file() else {}env = {**os.environ,- **{k: v for k in DEPLOY_CREDENTIALS if (v := local.get(k) or os.environ.get(k))},+ **{k: v for k in DEPLOY_CREDENTIALS if (v := os.environ.get(k) or local.get(k))},}if build_only:return runner([mda, "build", str(staged)], env)ask = confirm or (lambda question: input(f"{question} [y/N] ").strip().lower() in {"y", "yes"})- if not yes and not ask("Deploy this to your LangSmith workspace now?"):+ if not yes and not ask(f"Deploy this to your LangSmith workspace now as {name!r}?"):print("Not deployed.")return 1if not env.get("LANGSMITH_API_KEY"):@@ -248,4 +249,4 @@ def deploy_main("problem: LANGSMITH_API_KEY is not set (in .env or the environment). Nothing was deployed.")return 1- return runner([mda, "deploy", str(staged), "--name", "design-agent"], env)+ return runner([mda, "deploy", str(staged), "--name", name], env)diff --git a/src/design_agent/middleware/tool_history.py b/src/design_agent/middleware/tool_history.pyindex aede7bd..0ceaabb 100644--- a/src/design_agent/middleware/tool_history.py+++ b/src/design_agent/middleware/tool_history.py@@ -8,13 +8,25 @@ tool search writes tool names into history, in `tool_search_tool_result` blocksremoving any tool would poison every thread that ever searched. A retry cannot help.`ToolHistoryMiddleware` sends a valid view of the checkpoint; the checkpoint itself is never-rewritten. On every call it drops references the request cannot satisfy (`sanitize_history`). If-the provider still rejects the history, one deeper repair (`repair_history`) removes every-server-tool block pair and tool reference and folds each answered call to a missing tool, with an+rewritten. On every call it drops references the request cannot satisfy and any server tool call+the provider will never answer (`sanitize_history`). If the provider still rejects the history,+one deeper repair (`repair_history`) removes every server-tool block pair and tool reference+before the latest assistant turn, and folds each answered call to a missing tool there, with anexcerpt of its result, into a text note; the call is retried once, and the repair stays on forthat thread. Only the repair folds calls: a tool can be missing for one run (an MCP server thatdid not load), and folding then would cut that server's earlier results down to an excerpt.+The latest assistant turn is every message after the last human one; Anthropic reads its replies+and tool results as one assistant message, and two rules apply to it:+- A tool search made beside client tool calls ends its reply unanswered; the provider runs it at+ the start of the next reply, but only while the turn is open. A human message after the tool+ results (a steer, a budget note) closes the turn, and the search then 400s as a+ `server_tool_use` without its result. So every call drops a server call that can no longer be+ answered: any unanswered one except at the end of the open turn's last reply.+- Its thinking must be sent as the model wrote it ("thinking blocks in the latest assistant+ message cannot be modified"), so the repair leaves that turn as written. Dropping the turn+ instead would make the model redo calls it already made.+A provider 400 is read in-process to tell a history fault (`messages.N`, a tool reference,`input[N]`) from a code fault (a bad tool schema). `StaleHistoryError` carries fixed text, so theprovider's message never reaches the model or the channel.@@ -32,7 +44,7 @@ import anthropicimport openaifrom langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponsefrom langchain_core.exceptions import ContextOverflowError, ModelInvalidRequestError-from langchain_core.messages import AIMessage, AnyMessage, BaseMessage, ToolMessage+from langchain_core.messages import AIMessage, AnyMessage, BaseMessage, SystemMessage, ToolMessagefrom langgraph.config import get_configfrom design_agent.middleware.model_retry import exception_chain@@ -53,6 +65,7 @@ _SERVER_BLOCK_TYPES = frozenset("mcp_tool_result",})+_SERVER_CALL_TYPES = frozenset({"server_tool_use", "mcp_tool_use"})_THINKING_TYPES = frozenset({"thinking", "redacted_thinking"})_EXCERPT_CHARS = 400_NO_REFERENCES_TEXT = "No matching tools are available."@@ -97,14 +110,15 @@ def available_tool_names(tools: Iterable[Any]) -> frozenset[str]:def sanitize_history(messages: Sequence[BaseMessage], available: frozenset[str]) -> tuple[list[BaseMessage], HistoryReport]:- """Drop tool references the request cannot satisfy. Everything else is sent as checkpointed."""+ """Drop tool references the request cannot satisfy and server calls nothing will answer."""return _Rewrite(messages, available, repair=False).run()def repair_history(messages: Sequence[BaseMessage], available: frozenset[str]) -> tuple[list[BaseMessage], HistoryReport]:- """Remove every server-tool pair and tool reference; fold answered calls to missing tools."""+ """Before the latest turn, drop server-tool pairs and references and fold calls to missing+ tools; the latest turn gets only what `sanitize_history` does."""return _Rewrite(messages, available, repair=True).run()@@ -117,13 +131,38 @@ class _Rewrite:self.messages = list(messages)self.available = availableself.repair = repair+ self.deep = False # whether the message being rewritten gets the repairself.report = HistoryReport()+ # The latest assistant turn starts right after the last human message.+ self.turn = next(+ (i + 1 for i in reversed(range(len(self.messages))) if _human(self.messages[i])), 0+ )+ last_reply = max(+ (i for i, m in enumerate(self.messages) if isinstance(m, AIMessage)), default=-1+ )+ blocks = [+ (i, block)+ for i, message in enumerate(self.messages)+ if isinstance(message.content, list)+ for block in message.content+ if isinstance(block, dict)+ ]+ results = {b.get("tool_use_id") for _, b in blocks if b.get("type") in _SERVER_BLOCK_TYPES}+ # A server call with no result will never get one, unless it ends the open turn's last+ # reply: the provider runs that one at the start of the next reply.+ self.unanswered = {+ b.get("id")+ for i, b in blocks+ if b.get("type") in _SERVER_CALL_TYPES+ and b.get("id") not in results+ and not (i == last_reply and i >= self.turn)+ }answered = {m.tool_call_id: m for m in self.messages if isinstance(m, ToolMessage)}- # Only the repair folds, and only answered calls: a call still awaiting its result is the- # tail of an in-flight turn, and folding it would strand the result about to be appended.+ # Only the repair folds, and only answered calls before the latest turn: a call awaiting+ # its result is the tail of an in-flight turn, and folding it would strand that result.self.folded: dict[str, ToolMessage] = {}if repair:- for message in self.messages:+ for message in self.messages[: self.turn]:if not isinstance(message, AIMessage):continuefor call in message.tool_calls:@@ -137,9 +176,11 @@ class _Rewrite:def run(self) -> tuple[list[BaseMessage], HistoryReport]:out: list[BaseMessage] = []- for message in self.messages:+ for index, message in enumerate(self.messages):if isinstance(message, ToolMessage) and message.tool_call_id in self.folded:continue # its content rides in the note that replaced the call+ self.deep = self.repair and index < self.turn+ written = messageif isinstance(message, AIMessage) and self.folded:message = self._fold_calls(message)if isinstance(message.content, list):@@ -147,8 +188,14 @@ class _Rewrite:blocks = rewrite(message.content)if blocks is not message.content:message = message.model_copy(update={"content": blocks})- if isinstance(message, AIMessage) and self._emptied(message):- continue # a turn the repair left without content is omitted, never sent blank+ # A reply this pass left without content is omitted, never sent blank; one in the+ # latest turn is kept, since that turn's thinking must reach the provider as written.+ if (+ index < self.turn+ and isinstance(message, AIMessage)+ and self._emptied(message, written)+ ):+ continueout.append(message)return (out if self.report.changed else self.messages), self.report@@ -177,9 +224,9 @@ class _Rewrite:kept = [call for call in message.tool_calls if call.get("id") not in folded_ids]return message.model_copy(update={"content": blocks, "tool_calls": kept})- def _emptied(self, message: AIMessage) -> bool:+ def _emptied(self, message: AIMessage, written: BaseMessage) -> bool:return (- self.repair+ (self.deep or message is not written)and not message.tool_callsand isinstance(message.content, list)and all(@@ -205,7 +252,8 @@ class _Rewrite:def _block(self, block: dict[str, Any]) -> dict[str, Any] | None:block_type = block.get("type")- if self.repair and block_type in _SERVER_BLOCK_TYPES:+ unanswered = block_type in _SERVER_CALL_TYPES and block.get("id") in self.unanswered+ if unanswered or (self.deep and block_type in _SERVER_BLOCK_TYPES):self.report.dropped_server_blocks += 1return Noneif block_type == "tool_reference":@@ -225,9 +273,9 @@ class _Rewrite:return blockdef _drops(self, ref: Any) -> bool:- """Record and drop a reference the request cannot satisfy (every reference, in repair)."""+ """Record and drop a reference the request cannot satisfy (every one the repair reaches)."""name = ref.get("tool_name") if isinstance(ref, dict) else None- if not isinstance(name, str) or (name in self.available and not self.repair):+ if not isinstance(name, str) or (name in self.available and not self.deep):return Falseself.report.dropped_references.append(name)return True@@ -244,6 +292,11 @@ class _Rewrite:return {"type": "text", "text": note + "]"}+def _human(message: BaseMessage) -> bool:+ """A message the provider sends as user content of its own, not as a tool result."""+ return not isinstance(message, AIMessage | ToolMessage | SystemMessage)++def _text_of(content: Any) -> str:if isinstance(content, str):return contentdiff --git a/src/design_agent/models/factory.py b/src/design_agent/models/factory.pyindex 172fbb4..f0cfcf3 100644--- a/src/design_agent/models/factory.py+++ b/src/design_agent/models/factory.py@@ -1,14 +1,16 @@"""Build chat models for each role from settings and the capability registry.-Direct providers by default; `langsmith:provider/model` opts into the LangSmith Gateway. The SDK's-own retries are off: `TransientModelRetryMiddleware` owns recovery, bounded and logged in one-place. Every call has a stall ceiling.+Direct providers by default; `langsmith:provider/model` opts into the LangSmith Gateway. Anthropic+and OpenAI models go through the gateway's native routes, so they keep their own API (prompt+caching, context editing, tool search, effort); other providers use its shared OpenAI-style route.+The SDK's own retries are off: `TransientModelRetryMiddleware` owns recovery, bounded and logged in+one place. Every call has a stall ceiling."""from __future__ import annotationsimport os-from dataclasses import dataclass+from dataclasses import dataclass, replacefrom pathlib import Pathfrom typing import Any, Literal@@ -27,6 +29,10 @@ from design_agent.models.registry import (Role = Literal["lead", "helper", "look", "tool_selector", "learning"]VISION_ROLES: frozenset[Role] = frozenset({"lead", "helper", "look"})SDK_MAX_RETRIES = 0+#: The gateway origin is pinned, never read from settings, so no setting can send its key elsewhere.+GATEWAY_ORIGIN = "https://gateway.smith.langchain.com"+#: Providers the gateway serves on their own API, which keeps their native features.+GATEWAY_NATIVE_ROUTES = {"anthropic": "/anthropic", "openai": "/openai/v1"}@dataclass(frozen=True)@@ -97,10 +103,16 @@ def build_chat_model(kwargs.update(overrides)if spec.via_gateway:+ upstream = spec.upstream+ # Never "" -> provider key: a missing gateway key must fail at the gateway, not leak.+ kwargs.setdefault("api_key", _gateway_key(settings))+ if upstream.provider in GATEWAY_NATIVE_ROUTES:+ kwargs.setdefault("base_url", GATEWAY_ORIGIN + GATEWAY_NATIVE_ROUTES[upstream.provider])+ native = replace(resolved, spec=upstream)+ build = _anthropic if upstream.provider == "anthropic" else _openai+ return build(settings, native, kwargs)from langchain.chat_models import init_chat_model- if settings.langsmith_gateway_api_key is not None and "api_key" not in kwargs:- kwargs["api_key"] = settings.langsmith_gateway_api_key.get_secret_value()gateway: BaseChatModel = init_chat_model(str(spec), **kwargs)return gatewayif spec.provider == "anthropic":@@ -164,6 +176,14 @@ def _openai(settings: Settings, resolved: ResolvedModel, kwargs: dict[str, Any])return ChatOpenAI(model=resolved.spec.model, **kwargs)+def _gateway_key(settings: Settings) -> str:+ """The gateway credential: its own key, else the LangSmith key; "" when there is neither."""+ for key in (settings.langsmith_gateway_api_key, settings.langsmith_api_key):+ if key is not None and key.get_secret_value():+ return key.get_secret_value()+ return ""++def _named_key(env_name: str | None, project_root: Path | None) -> str | None:"""The value of the variable `env_name` from the process or the project `.env`."""if not env_name:diff --git a/src/design_agent/models/registry.py b/src/design_agent/models/registry.pyindex fefbc71..3ce22eb 100644--- a/src/design_agent/models/registry.py+++ b/src/design_agent/models/registry.py@@ -134,6 +134,9 @@ CAPABILITY_REGISTRY: dict[str, ModelCapabilities] = {),}+#: Providers the LangSmith Gateway serves on their own API (`models.factory.GATEWAY_NATIVE_ROUTES`).+GATEWAY_NATIVE_PROVIDERS = frozenset({"anthropic", "openai"})+UNKNOWN_MODEL = ModelCapabilities(provider="",vision=False,@@ -142,10 +145,13 @@ UNKNOWN_MODEL = ModelCapabilities(def capabilities_for(spec: ModelSpec, *, base_url: str | None = None) -> ModelCapabilities:- """Exact lookup. A gateway or custom endpoint never inherits provider-native features."""+ """Exact lookup. A custom endpoint, or a gateway route that is not the provider's own API,+ never inherits provider-native features."""if spec.via_gateway:upstream = CAPABILITY_REGISTRY.get(str(spec.upstream), UNKNOWN_MODEL)- return _portable(upstream, "LangSmith Gateway: standard endpoint, portable selector.")+ if spec.upstream.provider in GATEWAY_NATIVE_PROVIDERS:+ return upstream+ return _portable(upstream, "LangSmith Gateway shared route: portable selector.")found = CAPABILITY_REGISTRY.get(str(spec), UNKNOWN_MODEL)if base_url is not None and found.disclosure is ToolDisclosure.PROVIDER_NATIVE:return _portable(found, "custom base URL: provider-native search is not assumed.")diff --git a/tests/unit/test_config_and_registry.py b/tests/unit/test_config_and_registry.pyindex af682eb..2eaec7e 100644--- a/tests/unit/test_config_and_registry.py+++ b/tests/unit/test_config_and_registry.py@@ -5,9 +5,11 @@ from __future__ import annotationsimport pytestfrom design_agent.config import ModelSpec, Settings-from design_agent.models.factory import build_chat_model, resolve_model+from design_agent.models.cache import CachedChatAnthropic+from design_agent.models.factory import GATEWAY_NATIVE_ROUTES, build_chat_model, resolve_modelfrom design_agent.models.registry import (CAPABILITY_REGISTRY,+ GATEWAY_NATIVE_PROVIDERS,HIGH_EFFORT_MIN_OUTPUT_TOKENS,UNKNOWN_MODEL,ModelConfigurationError,@@ -35,9 +37,42 @@ def test_lookup_is_exact_never_substring() -> None:assert capabilities_for(ModelSpec.parse("anthropic:claude-opus")) is UNKNOWN_MODEL-def test_gateway_and_custom_base_url_never_claim_native_search() -> None:- gateway = capabilities_for(ModelSpec.parse("langsmith:anthropic/claude-opus-5-5"))- assert gateway.disclosure is ToolDisclosure.PORTABLE_SELECTOR+def test_the_gateway_keeps_native_features_only_on_a_providers_own_route() -> None:+ native = capabilities_for(ModelSpec.parse("langsmith:anthropic/claude-opus-5-5"))+ assert native == CAPABILITY_REGISTRY["anthropic:claude-opus-5-5"]+ shared = capabilities_for(ModelSpec.parse("langsmith:google_genai/gemini-3-pro"))+ assert shared.disclosure is ToolDisclosure.PORTABLE_SELECTOR+ assert set(GATEWAY_NATIVE_ROUTES) == GATEWAY_NATIVE_PROVIDERS+++def test_a_gateway_anthropic_model_is_the_native_class_on_the_gateway_route() -> None:+ s = settings(+ model="langsmith:anthropic/claude-opus-5-5",+ langsmith_gateway_api_key="lsv2_gateway",+ anthropic_api_key="sk-ant-never-sent",+ )+ model = build_chat_model(s, "lead")+ assert isinstance(model, CachedChatAnthropic)+ assert model.model == "claude-opus-5-5"+ assert model.anthropic_api_url == "https://gateway.smith.langchain.com/anthropic"+ assert model.anthropic_api_key.get_secret_value() == "lsv2_gateway"+ assert (model.effort, model.thinking, model.cache_ttl) == ("high", {"type": "adaptive"}, "1h")+++def test_the_gateway_falls_back_to_the_langsmith_key_and_never_to_a_provider_key() -> None:+ s = settings(model="langsmith:anthropic/claude-opus-5-5", langsmith_api_key="lsv2_workspace")+ assert build_chat_model(s, "lead").anthropic_api_key.get_secret_value() == "lsv2_workspace" # type: ignore[attr-defined]+ keyless = settings(model="langsmith:anthropic/claude-opus-5-5", anthropic_api_key="sk-ant-x")+ assert build_chat_model(keyless, "lead").anthropic_api_key.get_secret_value() == "" # type: ignore[attr-defined]+++def test_a_gateway_openai_model_uses_the_openai_route() -> None:+ s = settings(model="langsmith:openai/gpt-6-sol", langsmith_gateway_api_key="lsv2_gateway")+ model = build_chat_model(s, "lead")+ assert model.openai_api_base == "https://gateway.smith.langchain.com/openai/v1" # type: ignore[attr-defined]+++def test_custom_base_url_never_claims_native_search() -> None:proxied = capabilities_for(ModelSpec.parse("openai:gpt-6-sol"), base_url="https://proxy.example")diff --git a/tests/unit/test_guards.py b/tests/unit/test_guards.pyindex c864973..c6fbd8d 100644--- a/tests/unit/test_guards.py+++ b/tests/unit/test_guards.py@@ -112,7 +112,7 @@ def test_history_drops_references_to_missing_tools_and_repair_folds_their_calls(content="", tool_calls=[{"name": "gone_tool", "args": {}, "id": "c1", "type": "tool_call"}])result = ToolMessage("the old result", tool_call_id="c1", name="gone_tool")- history = [HumanMessage("hi"), search, call, result]+ history = [HumanMessage("hi"), search, call, result, HumanMessage("next")]sent, report = sanitize_history(history, frozenset({"kept_tool"}))assert report.dropped_references == ["gone_tool"]refs = sent[1].content[0]["content"]["tool_references"] # type: ignore[index]diff --git a/tests/unit/test_tool_history.py b/tests/unit/test_tool_history.pynew file mode 100644index 0000000..58ab7ac--- /dev/null+++ b/tests/unit/test_tool_history.py@@ -0,0 +1,205 @@+"""History repair against the two provider rules about the latest assistant turn.++Anthropic reads every message after the last human one as one assistant message: a tool search+left at the end of that turn's last reply is answered at the start of the next reply, and that+turn's thinking must be sent exactly as written. Earlier turns can be rewritten.+"""++from __future__ import annotations++from typing import Any++import anthropic+import httpx+import pytest+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage++from design_agent.middleware.tool_history import (+ StaleHistoryError,+ ToolHistoryMiddleware,+ repair_history,+ sanitize_history,+)++TOOLS = frozenset({"ls", "read_file", "tool_search_tool_bm25"})+++def thinking(text: str) -> dict[str, Any]:+ return {"type": "thinking", "thinking": text, "signature": f"sig-{text}"}+++def search(call_id: str) -> dict[str, Any]:+ return {+ "type": "server_tool_use",+ "id": call_id,+ "name": "tool_search_tool_bm25",+ "input": {"query": "paper"},+ }+++def search_result(call_id: str, *names: str) -> dict[str, Any]:+ refs = [{"type": "tool_reference", "tool_name": name} for name in names]+ return {+ "type": "tool_search_tool_result",+ "tool_use_id": call_id,+ "content": {"type": "tool_search_tool_search_result", "tool_references": refs},+ }+++def tool_use(call_id: str, name: str) -> dict[str, Any]:+ return {"type": "tool_use", "id": call_id, "name": name, "input": {}}+++def reply(*blocks: dict[str, Any]) -> AIMessage:+ calls = [+ {"id": b["id"], "name": b["name"], "args": {}, "type": "tool_call"}+ for b in blocks+ if b["type"] == "tool_use"+ ]+ return AIMessage(content=list(blocks), tool_calls=calls)+++def result(call_id: str, text: str = "ok") -> ToolMessage:+ return ToolMessage(content=text, tool_call_id=call_id)+++def server_ids(messages: list[BaseMessage]) -> list[str]:+ return [+ b["id"]+ for m in messages+ if isinstance(m.content, list)+ for b in m.content+ if isinstance(b, dict) and b.get("type") == "server_tool_use"+ ]+++def deferred_search_turn() -> list[BaseMessage]:+ """A first reply that ran two tools and left a search for the next reply, as in prod."""+ return [+ HumanMessage("make the deck"),+ reply(thinking("plan"), tool_use("c1", "ls"), tool_use("c2", "read_file"), search("s1")),+ result("c1"),+ result("c2"),+ ]+++def test_a_search_left_at_the_end_of_the_open_turn_is_sent_for_the_provider_to_answer() -> None:+ messages = deferred_search_turn()+ sent, report = sanitize_history(messages, TOOLS)+ assert sent == messages and not report.changed+++def test_a_human_message_after_the_tool_results_closes_the_turn_and_drops_the_search() -> None:+ messages = [*deferred_search_turn(), HumanMessage("also make it blue")]+ sent, report = sanitize_history(messages, TOOLS)+ assert server_ids(sent) == [] and report.dropped_server_blocks == 1+ assert [b["type"] for b in sent[1].content] == ["thinking", "tool_use", "tool_use"] # type: ignore[union-attr]+++def test_a_later_reply_means_the_earlier_unanswered_search_will_never_be_answered() -> None:+ messages = [+ *deferred_search_turn(),+ reply(thinking("next"), tool_use("c3", "ls")),+ result("c3"),+ ]+ sent, _ = sanitize_history(messages, TOOLS)+ assert server_ids(sent) == []+++def test_references_to_missing_tools_are_dropped_and_bound_ones_kept() -> None:+ messages = [+ HumanMessage("hi"),+ reply(search("s1"), search_result("s1", "read_file", "paper_gone")),+ HumanMessage("next"),+ ]+ sent, report = sanitize_history(messages, TOOLS)+ refs = sent[1].content[1]["content"]["tool_references"] # type: ignore[index]+ assert [r["tool_name"] for r in refs] == ["read_file"]+ assert report.dropped_references == ["paper_gone"]+++def latest_turn_with_interleaved_searches() -> list[BaseMessage]:+ return [+ HumanMessage("first ask"),+ reply(search("old"), search_result("old", "read_file"), tool_use("c0", "gone_tool")),+ result("c0", "earlier output"),+ HumanMessage("second ask"),+ reply(+ thinking("a"),+ search("s1"),+ search_result("s1", "read_file"),+ thinking("b"),+ search("s2"),+ search_result("s2", "ls"),+ thinking("c"),+ tool_use("c1", "ls"),+ ),+ result("c1"),+ ]+++def test_the_repair_leaves_the_latest_turn_exactly_as_written() -> None:+ messages = latest_turn_with_interleaved_searches()+ sent, report = repair_history(messages, TOOLS)+ assert sent[-2:] == messages[-2:]+ assert sent[-2] is messages[-2], "the latest reply's thinking reaches the provider as written"+ assert "old" not in server_ids(sent) and report.dropped_server_blocks == 2+++def test_the_repair_folds_answered_calls_to_missing_tools_only_before_the_latest_turn() -> None:+ messages = latest_turn_with_interleaved_searches()+ sent, report = repair_history(messages, TOOLS)+ assert report.folded_calls == ["gone_tool"]+ assert not any(isinstance(m, ToolMessage) and m.tool_call_id == "c0" for m in sent)+ note = sent[1].content[0]["text"] # type: ignore[index]+ assert "gone_tool" in note and "earlier output" in note+++def rejection(message: str) -> anthropic.BadRequestError:+ request = httpx.Request("POST", "https://api.anthropic.com/v1/messages")+ response = httpx.Response(400, request=request)+ body = {"error": {"type": "invalid_request_error", "message": message}}+ return anthropic.BadRequestError(message, response=response, body=body)+++class FakeRequest:+ def __init__(self, messages: list[BaseMessage]) -> None:+ self.messages = messages+ self.tools = [{"name": name} for name in sorted(TOOLS)]++ def override(self, **changes: Any) -> FakeRequest:+ return FakeRequest(changes.get("messages", self.messages))+++async def test_a_thread_already_repairing_keeps_its_latest_turn_whole_on_the_first_try() -> None:+ middleware = ToolHistoryMiddleware()+ messages = latest_turn_with_interleaved_searches()+ seen: list[list[BaseMessage]] = []++ async def provider(request: Any) -> str:+ seen.append(request.messages)+ latest = request.messages[-2]+ if latest is not messages[-2]:+ raise rejection(+ "messages.3.content.7: thinking blocks in the latest assistant message cannot be modified"+ )+ if "old" in server_ids(request.messages):+ raise rejection("messages.1: tool reference 'read_file' needs a repair")+ return "ok"++ assert await middleware.awrap_model_call(FakeRequest(messages), provider) == "ok" # type: ignore[arg-type]+ assert len(seen) == 2, "one rejection, one repaired retry"+ seen.clear()+ assert await middleware.awrap_model_call(FakeRequest(messages), provider) == "ok" # type: ignore[arg-type]+ assert len(seen) == 1, "the repair stays on for the thread and passes first time"+++async def test_a_history_the_repair_cannot_fix_raises_fixed_text() -> None:+ async def provider(_request: Any) -> str:+ raise rejection("messages.0: something about tool_use the repair cannot fix")++ with pytest.raises(StaleHistoryError, match="even after repair"):+ await ToolHistoryMiddleware().awrap_model_call(+ FakeRequest(latest_turn_with_interleaved_searches()), # type: ignore[arg-type]+ provider,+ )