Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

Keep native features on the LangSmith Gateway; port the latest-turn history rules

Amal Irgashev16571416f64d
diff --git a/docs/cli.md b/docs/cli.md
index 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.md
index 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 by
default; 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.py
index 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_main
sys.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.py
index 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 1
if 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.py
index 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` blocks
removing 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 an
excerpt of its result, into a text note; the call is retried once, and the repair stays on for
that thread. Only the repair folds calls: a tool can be missing for one run (an MCP server that
did 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 the
provider's message never reaches the model or the channel.
@@ -32,7 +44,7 @@ import anthropic
import openai
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
from langchain_core.exceptions import ContextOverflowError, ModelInvalidRequestError
-from langchain_core.messages import AIMessage, AnyMessage, BaseMessage, ToolMessage
+from langchain_core.messages import AIMessage, AnyMessage, BaseMessage, SystemMessage, ToolMessage
from langgraph.config import get_config
from 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 = available
self.repair = repair
+ self.deep = False # whether the message being rewritten gets the repair
self.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):
continue
for 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 = message
if 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)
+ ):
+ continue
out.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_calls
and 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 += 1
return None
if block_type == "tool_reference":
@@ -225,9 +273,9 @@ class _Rewrite:
return block
def _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 False
self.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 content
diff --git a/src/design_agent/models/factory.py b/src/design_agent/models/factory.py
index 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 annotations
import os
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from pathlib import Path
from 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 gateway
if 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.py
index 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.py
index 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 annotations
import pytest
from 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_model
from 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.py
index 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.py
new file mode 100644
index 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,
+ )