deep-agent-cli 0.1.0__py3-none-any.whl

agent/factory.py

@@ -0,0 +1,232 @@
+# Assembly entry: create_deep_agent() only. Do not fork Deep Agents core.
+# Middleware augments the Deep Agents defaults; create_deep_agent remains the only assembly entry.
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+from typing import Any, Callable
+
+from deepagents import (
+    GeneralPurposeSubagentProfile,
+    HarnessProfile,
+    create_deep_agent,
+    register_harness_profile,
+)
+from deepagents.backends.protocol import BackendProtocol, SandboxBackendProtocol
+from deepagents.middleware.summarization import (
+    SummarizationToolMiddleware,
+    create_summarization_tool_middleware,
+)
+from deepagents._models import get_model_identifier, get_model_provider
+from langchain.agents.middleware import TodoListMiddleware
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
+from langgraph.checkpoint.memory import InMemorySaver
+
+from agent.config import SandboxConfig, Settings
+from agent.control import RunController
+from agent.llm import build_chat_model
+from agent.middleware.cancel_tools import ToolCancelMiddleware
+from agent.middleware.attachments import AttachmentMaterializationMiddleware
+from agent.middleware.pause import PauseGateMiddleware
+from agent.middleware.recovery import RecoveryContextMiddleware
+from agent.middleware.steering import SteeringMiddleware
+from agent.middleware.tool_arg_hints import ToolArgHintMiddleware
+from agent.middleware.write_operation import WriteOperationMiddleware
+from agent.middleware.workspace_filesystem import WorkspaceFilesystemMiddleware
+from agent.permission import (
+    PermissionMode, allow_mode_unavailable_reason, interrupt_on_for_mode,
+    permission_mode_from_interrupt_on,
+)
+from agent.sandbox import ExecutionMode, SKILLS_ROOT, WorkspaceCompositeBackend, select_backend
+from agent.tools.execute import build_execute_tool
+from agent.tools.human_input import build_human_input_tools
+from agent.tools.web_search import build_web_search_tool
+
+DEFAULT_FS_TOOLS = ["ls", "read_file", "glob", "grep", "write_file", "edit_file", "delete"]
+DEFAULT_SYSTEM_PROMPT = (
+    "你是使用 {model_name} 的 Coding Agent CLI。"
+    "完成用户请求后直接报告结果。"
+    "如果继续执行需要用户提供信息或从多个选项中做决定，调用 request_human_input 暂停等待回答。"
+    "如果你主动给用户列出多个后续操作供其选择，也必须调用 request_human_input，"
+    "用 fields 的 single_select 或 multi_select 表达选项；不要只在普通回复中写编号菜单。"
+)
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    instructions: str | None = None
+    tools: tuple[BaseTool, ...] = ()
+    skills: tuple[str, ...] | None = None
+    backend: BackendProtocol | None = None
+    sandbox: SandboxConfig | None = None
+    web_search_api_key: str | None = field(default=None, repr=False)
+
+
+@dataclass
+class PreparedAgent:
+    graph: Any
+    backend: BackendProtocol
+    model: BaseChatModel | None = None
+    spec: AgentSpec = field(default_factory=AgentSpec)
+    interrupt_on: dict[str, Any] = field(default_factory=dict)
+    system_prompt: str = ""
+    exposed_tool_names: list[str] = field(default_factory=list)
+    filesystem_tools: list[str] = field(default_factory=list)
+    execution_mode: ExecutionMode = ExecutionMode.CUSTOM
+    security_warning: str = ""
+    checkpointer: Any = None
+    run_controller: RunController | None = None
+    pause_condition: Callable[[], bool] = field(default=lambda: False)
+    compact_middleware: SummarizationToolMiddleware | None = None
+
+
+def compose_system_prompt(spec: AgentSpec, model: BaseChatModel, workspace: Path) -> str:
+    model_name = str(getattr(model, "model_name", None) or get_model_identifier(model) or type(model).__name__)
+    sections = [DEFAULT_SYSTEM_PROMPT.format(model_name=model_name)]
+    if spec.instructions and spec.instructions.strip():
+        sections.append(f"# User Instructions\n{spec.instructions.strip()}")
+    project_instructions = workspace.expanduser().resolve() / "AGENTS.md"
+    if project_instructions.is_file():
+        sections.append(f"# Project Instructions\n{project_instructions.read_text(encoding='utf-8')}")
+    return "\n\n".join(sections)
+
+
+def build_agent(
+    spec: AgentSpec,
+    model: BaseChatModel,
+    permission: PermissionMode,
+    checkpointer: Any | None,
+    run_controller: RunController,
+    should_pause: Callable[[], bool],
+    interrupt_on_override: dict[str, Any] | None = None,
+) -> PreparedAgent:
+    sandbox_cfg = spec.sandbox or SandboxConfig()
+    if spec.backend is None:
+        selected = select_backend(sandbox_cfg)
+        fs_backend = selected.backend
+        execution_mode = selected.mode
+        security_warning = selected.warning
+    else:
+        fs_backend = spec.backend
+        execution_mode = ExecutionMode.CUSTOM
+        security_warning = ""
+    if permission is PermissionMode.ALLOW and execution_mode is not ExecutionMode.SANDBOXED:
+        raise ValueError(allow_mode_unavailable_reason(execution_mode))
+    _disable_general_purpose_task(model)
+    prompt = compose_system_prompt(spec, model, sandbox_cfg.workspace)
+    tools = [*build_human_input_tools(), *spec.tools]
+    if spec.web_search_api_key:
+        tools.append(build_web_search_tool(spec.web_search_api_key))
+    hitl = dict(interrupt_on_override) if interrupt_on_override is not None else (interrupt_on_for_mode(permission) or {})
+    filesystem_tools = list(DEFAULT_FS_TOOLS)
+    supports_execute = isinstance(fs_backend, SandboxBackendProtocol)
+    if supports_execute:
+        tools.append(build_execute_tool(
+            fs_backend,
+            network_by_default=permission is PermissionMode.ALLOW,
+        ))
+    skill_sources = list(spec.skills) if spec.skills is not None else (
+        _default_skill_sources(fs_backend) if spec.backend is None else None
+    )
+    saver = checkpointer if checkpointer is not None else InMemorySaver()
+    compact_middleware = create_summarization_tool_middleware(model, fs_backend)
+    graph = create_deep_agent(
+        model=model,
+        tools=tools,
+        system_prompt=prompt,
+        middleware=[
+            PauseGateMiddleware(lambda: run_controller.pause_requested or should_pause()),
+            RecoveryContextMiddleware(),
+            SteeringMiddleware(run_controller),
+            ToolCancelMiddleware(run_controller),
+            ToolArgHintMiddleware(),
+            WriteOperationMiddleware(fs_backend),
+            AttachmentMaterializationMiddleware(),
+            TodoListMiddleware(),
+            WorkspaceFilesystemMiddleware(backend=fs_backend, tools=filesystem_tools),
+            compact_middleware,
+        ],
+        skills=skill_sources,
+        backend=fs_backend,
+        interrupt_on=hitl or None,
+        checkpointer=saver,
+        name="deep-agent-template",
+    )
+    return PreparedAgent(
+        graph=graph,
+        backend=fs_backend,
+        model=model,
+        spec=spec,
+        interrupt_on=hitl,
+        system_prompt=prompt,
+        exposed_tool_names=[tool.name for tool in tools if tool.name != "request_human_input"],
+        filesystem_tools=filesystem_tools,
+        execution_mode=execution_mode,
+        security_warning=security_warning,
+        checkpointer=saver,
+        run_controller=run_controller,
+        pause_condition=should_pause,
+        compact_middleware=compact_middleware,
+    )
+
+
+def create_agent(
+    *,
+    model: BaseChatModel | None = None,
+    checkpointer: Any | None = None,
+    should_pause: Callable[[], bool] | None = None,
+    instructions: str | None = None,
+    extra_tools: list[BaseTool] | None = None,
+    interrupt_on: dict[str, Any] | None = None,
+    skills: list[str] | None = None,
+    settings: Settings | None = None,
+    backend: BackendProtocol | None = None,
+    sandbox_config: SandboxConfig | None = None,
+    run_controller: RunController | None = None,
+) -> PreparedAgent:
+    cfg = settings or Settings()
+    spec = AgentSpec(
+        instructions=instructions if instructions is not None else cfg.agent_instructions,
+        tools=tuple(extra_tools or ()),
+        skills=tuple(skills) if skills is not None else None,
+        backend=backend,
+        sandbox=sandbox_config or cfg.sandbox,
+        web_search_api_key=os.environ.get("TAVILY_API_KEY") or cfg.tavily_api_key,
+    )
+    permission = permission_mode_from_interrupt_on(interrupt_on) if interrupt_on is not None else PermissionMode.ASK
+    effective_interrupt_on = interrupt_on
+    if interrupt_on:
+        defaults = interrupt_on_for_mode(PermissionMode.ASK) or {}
+        for name, rule in defaults.items():
+            if name in interrupt_on and interrupt_on[name] != rule:
+                raise ValueError(f"Cannot override the default approval rule for {name}")
+        effective_interrupt_on = {**defaults, **interrupt_on}
+    return build_agent(
+        spec, model or _default_model(cfg), permission, checkpointer,
+        run_controller or RunController(), should_pause or (lambda: False),
+        interrupt_on_override=effective_interrupt_on,
+    )
+
+
+def _default_model(cfg: Settings) -> BaseChatModel:
+    return build_chat_model(cfg.active_profile, streaming=True)
+
+
+def _default_skill_sources(backend: BackendProtocol) -> list[str] | None:
+    if isinstance(backend, WorkspaceCompositeBackend) and backend.skills_dir is not None:
+        return [f"{SKILLS_ROOT}/"]
+    return None
+
+
+_NO_GP = HarnessProfile(general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False))
+
+
+def _disable_general_purpose_task(model: BaseChatModel) -> None:
+    provider = get_model_provider(model)
+    identifier = get_model_identifier(model)
+    if identifier:
+        key = identifier if ":" in identifier or not provider else f"{provider}:{identifier}"
+        register_harness_profile(key, _NO_GP)
+    elif provider:
+        # Models without an identifier cannot be targeted more narrowly upstream.
+        register_harness_profile(provider, _NO_GP)

agent/file_mutation.py

@@ -0,0 +1,5 @@
+"""Shared file mutation operation vocabulary."""
+from typing import Literal
+
+FileMutationOperation = Literal["create", "modify", "overwrite", "delete"]
+WriteOperation = Literal["create", "overwrite"]

agent/llm.py

@@ -0,0 +1,339 @@
+"""Qwen Responses compatibility without patching ``langchain-openai`` globally."""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+import base64
+from typing import Any, ClassVar
+
+import langchain_openai.chat_models.base as _lc_base
+from langchain_core.messages import BaseMessage, HumanMessage
+from langchain_core.messages.content import create_image_block, create_text_block
+from langchain_core.outputs import ChatGenerationChunk
+from langchain_openai import ChatOpenAI
+from pydantic import PrivateAttr, model_validator
+
+from agent.attachments import ATTACHMENT_META_KEY, AttachmentStore, refs_from_message
+from agent.config import ModelProfile
+
+
+_QWEN_REASONING_EVENT_TYPES = {
+    "response.reasoning_text.delta": "response.reasoning_summary_text.delta",
+    # 1.6.x does not consume this event yet, but normalize it without inventing
+    # any fields in case an upstream converter starts doing so.
+    "response.reasoning_text.done": "response.reasoning_summary_text.done",
+}
+
+
+class ResponsesEventProxy:
+    """Read-only view over an OpenAI SDK event; the source object is untouched."""
+
+    __slots__ = ("_event", "_type")
+
+    def __init__(self, event: Any, event_type: str) -> None:
+        self._event = event
+        self._type = event_type
+
+    @property
+    def type(self) -> str:
+        return self._type
+
+    @property
+    def summary_index(self) -> int:
+        # Qwen's streamed reasoning is the final summary. content_index has a
+        # different Responses meaning and must not be reused here.
+        return 0
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._event, name)
+
+
+def normalize_qwen_responses_event(event: Any) -> Any:
+    """Normalize only Qwen's reasoning event spelling for LangChain 1.6.x."""
+    event_type = _QWEN_REASONING_EVENT_TYPES.get(getattr(event, "type", None))
+    return event if event_type is None else ResponsesEventProxy(event, event_type)
+
+
+def materialize_attachment_refs(input_: Any, store: AttachmentStore | None) -> Any:
+    """Return request-local messages with image bytes; leave checkpoint messages unchanged."""
+    if not isinstance(input_, (list, tuple)):
+        return input_
+    messages: list[Any] = []
+    changed = False
+    for message in input_:
+        refs = refs_from_message(message) if isinstance(message, HumanMessage) else ()
+        if not refs:
+            messages.append(message)
+            continue
+        if store is None:
+            raise RuntimeError("Image attachment storage is not configured for this model")
+        blocks: list[dict[str, Any]] = []
+        content = message.content
+        if isinstance(content, str):
+            if content:
+                blocks.append(create_text_block(content))
+        elif isinstance(content, list):
+            blocks.extend(content)
+        for ref in refs:
+            attachment = store.read(ref)
+            blocks.append(create_image_block(
+                base64=base64.b64encode(attachment.data).decode("ascii"),
+                mime_type=attachment.mime_type,
+            ))
+        additional = dict(message.additional_kwargs)
+        additional.pop(ATTACHMENT_META_KEY, None)
+        messages.append(message.model_copy(update={
+            "content": blocks,
+            "additional_kwargs": additional,
+        }))
+        changed = True
+    return messages if changed else input_
+
+
+class QwenChatOpenAI(ChatOpenAI):
+    """Qwen Responses adapter with ChatOpenAI-compatible fallback routing."""
+
+    _attachment_store: AttachmentStore | None = PrivateAttr(default=None)
+    materializes_attachment_refs: ClassVar[bool] = True
+
+    @model_validator(mode="before")
+    @classmethod
+    def _use_proxy_free_clients(cls, values: Any) -> Any:
+        """Keep direct construction safe from inherited WSL SOCKS settings too."""
+        if not isinstance(values, dict):
+            return values
+        if values.get("http_client") is None or values.get("http_async_client") is None:
+            import httpx
+
+            values = dict(values)
+            values.setdefault("http_socket_options", ())
+            if values.get("http_client") is None:
+                values["http_client"] = httpx.Client(trust_env=False)
+            if values.get("http_async_client") is None:
+                values["http_async_client"] = httpx.AsyncClient(trust_env=False)
+        return values
+
+    def set_attachment_store(self, store: AttachmentStore) -> None:
+        self._attachment_store = store
+
+    def _stream(self, *args: Any, **kwargs: Any) -> Iterator[ChatGenerationChunk]:
+        # ChatOpenAI routes directly to BaseChatOpenAI._stream_responses.
+        if self._use_responses_api({**kwargs, **self.model_kwargs}):
+            yield from self._stream_responses(*args, **kwargs)
+        else:
+            yield from super()._stream(*args, **kwargs)
+
+    async def _astream(self, *args: Any, **kwargs: Any) -> AsyncIterator[ChatGenerationChunk]:
+        # ChatOpenAI._astream directly calls BaseChatOpenAI._astream_responses,
+        # so it would bypass an override of _astream_responses on this class.
+        if self._use_responses_api({**kwargs, **self.model_kwargs}):
+            async for chunk in self._astream_responses(*args, **kwargs):
+                yield chunk
+        else:
+            async for chunk in super()._astream(*args, **kwargs):
+                yield chunk
+
+    def _get_request_payload(
+        self,
+        input_: Any,
+        *,
+        stop: list[str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Keep the Gateway's documented nested ``extra_body`` on the wire.
+
+        OpenAI SDK treats an outer ``extra_body`` argument as transport options
+        and merges it into JSON. This extra envelope is removed once by that
+        SDK, producing Gateway's required ``{"extra_body": {...}}`` body.
+        """
+        materialized = self._materialize_attachments(input_)
+        payload = super()._get_request_payload(materialized, stop=stop, **kwargs)
+        if not self._use_responses_api({**kwargs, **self.model_kwargs}):
+            return payload
+        extra_body = payload.get("extra_body")
+        if isinstance(extra_body, dict) and set(extra_body) != {"extra_body"}:
+            payload["extra_body"] = {"extra_body": extra_body}
+        return payload
+
+    def _materialize_attachments(self, input_: Any) -> Any:
+        return materialize_attachment_refs(input_, self._attachment_store)
+
+    def _stream_responses(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> Iterator[ChatGenerationChunk]:
+        """LangChain's sync Responses loop with Qwen event normalization."""
+        self._ensure_sync_client_available()
+        kwargs["stream"] = True
+        payload = self._get_request_payload(messages, stop=stop, **kwargs)
+        headers: dict[str, Any] = {}
+        base_generation_info: dict[str, Any] = {}
+        try:
+            if self.include_response_headers or self._uses_gateway:
+                raw_context_manager = self.root_client.with_raw_response.responses.create(**payload)
+                context_manager = raw_context_manager.parse()
+                if self.include_response_headers:
+                    headers = {"headers": dict(raw_context_manager.headers)}
+                _lc_base._add_gateway_metadata(base_generation_info, raw_context_manager)
+            else:
+                context_manager = self.root_client.responses.create(**payload)
+
+            original_schema_obj = kwargs.get("response_format")
+            with context_manager as response:
+                is_first_chunk = True
+                current_index = current_output_index = current_sub_index = -1
+                has_reasoning = False
+                for raw_chunk in response:
+                    chunk = normalize_qwen_responses_event(raw_chunk)
+                    metadata = headers if is_first_chunk else {}
+                    current_index, current_output_index, current_sub_index, generation_chunk = (
+                        _lc_base._convert_responses_chunk_to_generation_chunk(
+                            chunk, current_index, current_output_index, current_sub_index,
+                            schema=original_schema_obj, metadata=metadata,
+                            has_reasoning=has_reasoning, output_version=self.output_version,
+                        )
+                    )
+                    if generation_chunk:
+                        if is_first_chunk and base_generation_info:
+                            generation_chunk.generation_info = {
+                                **base_generation_info,
+                                **(generation_chunk.generation_info or {}),
+                            }
+                        if run_manager:
+                            run_manager.on_llm_new_token(generation_chunk.text, chunk=generation_chunk)
+                        is_first_chunk = False
+                        if "reasoning" in generation_chunk.message.additional_kwargs:
+                            has_reasoning = True
+                        yield generation_chunk
+        except _lc_base.openai.BadRequestError as error:
+            _lc_base._handle_openai_bad_request(error)
+        except _lc_base.openai.APIError as error:
+            _lc_base._handle_openai_api_error(error)
+
+    async def _astream_responses(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[ChatGenerationChunk]:
+        """LangChain's Responses loop with one normalization before conversion."""
+        kwargs["stream"] = True
+        payload = self._get_request_payload(messages, stop=stop, **kwargs)
+        headers: dict[str, Any] = {}
+        base_generation_info: dict[str, Any] = {}
+        try:
+            if self.include_response_headers or self._uses_gateway:
+                raw_context_manager = await self.root_async_client.with_raw_response.responses.create(**payload)
+                context_manager = raw_context_manager.parse()
+                if self.include_response_headers:
+                    headers = {"headers": dict(raw_context_manager.headers)}
+                _lc_base._add_gateway_metadata(base_generation_info, raw_context_manager)
+            else:
+                context_manager = await self.root_async_client.responses.create(**payload)
+
+            original_schema_obj = kwargs.get("response_format")
+            async with context_manager as response:
+                is_first_chunk = True
+                current_index = current_output_index = current_sub_index = -1
+                has_reasoning = False
+                async for raw_chunk in _lc_base._astream_with_chunk_timeout(
+                    response, self.stream_chunk_timeout, model_name=self.model_name
+                ):
+                    chunk = normalize_qwen_responses_event(raw_chunk)
+                    metadata = headers if is_first_chunk else {}
+                    current_index, current_output_index, current_sub_index, generation_chunk = (
+                        _lc_base._convert_responses_chunk_to_generation_chunk(
+                            chunk, current_index, current_output_index, current_sub_index,
+                            schema=original_schema_obj, metadata=metadata,
+                            has_reasoning=has_reasoning, output_version=self.output_version,
+                        )
+                    )
+                    if generation_chunk:
+                        if is_first_chunk and base_generation_info:
+                            generation_chunk.generation_info = {
+                                **base_generation_info,
+                                **(generation_chunk.generation_info or {}),
+                            }
+                        if run_manager:
+                            await run_manager.on_llm_new_token(generation_chunk.text, chunk=generation_chunk)
+                        is_first_chunk = False
+                        if "reasoning" in generation_chunk.message.additional_kwargs:
+                            has_reasoning = True
+                        yield generation_chunk
+        except _lc_base.openai.BadRequestError as error:
+            _lc_base._handle_openai_bad_request(error)
+        except _lc_base.openai.APIError as error:
+            _lc_base._handle_openai_api_error(error)
+
+
+def chat_openai(
+    *,
+    model: str,
+    api_key: str,
+    base_url: str,
+    streaming: bool = True,
+    attachment_store: AttachmentStore | None = None,
+) -> QwenChatOpenAI:
+    # Ignore ALL_PROXY/HTTP_PROXY from the shell (common WSL/SOCKS setups break
+    # localhost gateways and require optional httpx[socks]).
+    import httpx
+
+    client = QwenChatOpenAI(
+        model=model,
+        api_key=api_key,
+        base_url=base_url,
+        streaming=streaming,
+        max_retries=2,
+        use_responses_api=True,
+        output_version="responses/v1",
+        reasoning={"effort": "low"},
+        extra_body={"enable_thinking": True},
+        http_socket_options=(),
+        http_client=httpx.Client(trust_env=False),
+        http_async_client=httpx.AsyncClient(trust_env=False),
+    )
+    if attachment_store is not None:
+        client.set_attachment_store(attachment_store)
+    return client
+
+
+def build_chat_model(
+    profile: ModelProfile,
+    *,
+    streaming: bool = True,
+    attachment_store: AttachmentStore | None = None,
+) -> ChatOpenAI:
+    """Build the template chat client from a ModelProfile."""
+    if profile.provider == "qwen-responses":
+        model = chat_openai(
+            model=profile.model,
+            api_key=profile.api_key,
+            base_url=profile.base_url,
+            streaming=streaming,
+            attachment_store=attachment_store,
+        )
+    elif profile.provider == "openai-compatible":
+        import httpx
+
+        model = ChatOpenAI(
+            model=profile.model,
+            api_key=profile.api_key,
+            base_url=profile.base_url,
+            streaming=streaming,
+            stream_usage=profile.stream_usage,
+            max_retries=2,
+            use_responses_api=False,
+            http_socket_options=(),
+            http_client=httpx.Client(trust_env=False),
+            http_async_client=httpx.AsyncClient(trust_env=False),
+        )
+    else:
+        raise ValueError(f"Unsupported model provider: {profile.provider}")
+    if profile.context_window > 0:
+        # deepagents reads this model profile to choose its 85% compaction
+        # threshold and to check the request's input budget.
+        model.profile = {**(model.profile or {}), "max_input_tokens": profile.context_window}
+    return model

agent/middleware/__init__.py

@@ -0,0 +1,9 @@
+from agent.middleware.cancel_tools import ToolCancelMiddleware
+from agent.middleware.pause import PauseGateMiddleware
+from agent.middleware.steering import SteeringMiddleware
+
+__all__ = [
+    "PauseGateMiddleware",
+    "SteeringMiddleware",
+    "ToolCancelMiddleware",
+]

agent/middleware/attachments.py

@@ -0,0 +1,31 @@
+"""Resolve image references only in model requests, leaving checkpoints compact."""
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Any, Callable
+
+from langchain.agents.middleware import AgentMiddleware
+from agent.attachments import AttachmentStore
+from agent.llm import QwenChatOpenAI, materialize_attachment_refs
+
+
+_active_store: ContextVar[AttachmentStore | None] = ContextVar("attachment_store", default=None)
+
+
+def set_attachment_store(store: AttachmentStore) -> Token[AttachmentStore | None]:
+    return _active_store.set(store)
+
+
+def reset_attachment_store(token: Token[AttachmentStore | None]) -> None:
+    _active_store.reset(token)
+
+
+class AttachmentMaterializationMiddleware(AgentMiddleware):
+    def wrap_model_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        if isinstance(request.model, QwenChatOpenAI):
+            return handler(request)
+        store = _active_store.get()
+        if store is None:
+            return handler(request)
+        messages = materialize_attachment_refs(request.messages, store)
+        return handler(request.override(messages=messages)) if messages is not request.messages else handler(request)

agent/middleware/cancel_tools.py

@@ -0,0 +1,39 @@
+"""Establish per-tool cancel contexts and optional cancellable tool hooks."""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+from agent.control import RunController
+
+
+class ToolCancelMiddleware(AgentMiddleware):
+    """Wrap each tool call with a cancel context bound to the active RunController."""
+
+    def __init__(self, controller: RunController) -> None:
+        super().__init__()
+        self._controller = controller
+
+    def wrap_tool_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        tool_call = getattr(request, "tool_call", None) or {}
+        tool_name = str(tool_call.get("name") or getattr(getattr(request, "tool", None), "name", "") or "tool")
+        tool_call_id = str(tool_call.get("id") or "")
+        ctx = self._controller.open_tool_context(tool_name=tool_name, tool_call_id=tool_call_id)
+        tool = getattr(request, "tool", None)
+        if tool is not None:
+            cancel = getattr(tool, "cancel", None)
+            if callable(cancel):
+                ctx.register_callback(cancel)
+        try:
+            if ctx.cancelled:
+                return ToolMessage(
+                    content="Cancelled by user.",
+                    tool_call_id=tool_call_id or tool_name,
+                    name=tool_name,
+                    status="error",
+                )
+            return handler(request)
+        finally:
+            self._controller.close_tool_context(ctx)

agent/middleware/pause.py

@@ -0,0 +1,18 @@
+# Pause at the next model-call safe point via LangGraph interrupt().
+# Do not build a custom pause engine; the checkpointer stores state and resume uses Command(resume=...).
+from collections.abc import Callable
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware
+from langgraph.types import interrupt
+
+
+class PauseGateMiddleware(AgentMiddleware):
+    def __init__(self, should_pause: Callable[[], bool]) -> None:
+        super().__init__()
+        self._should_pause = should_pause
+
+    def wrap_model_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        if self._should_pause():
+            interrupt({"type": "pause"})
+        return handler(request)