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

agent/middleware/recovery.py

@@ -0,0 +1,65 @@
+"""One-shot recovery context for model requests, never checkpoint messages."""
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import SystemMessage
+
+from agent.session import StopReason
+
+
+_active_context: ContextVar[RecoveryContext | None] = ContextVar("recovery_context", default=None)
+
+
+@dataclass
+class RecoveryContext:
+    text: str | None
+    armed: bool = False
+
+    @classmethod
+    def for_stop_reason(cls, reason: StopReason) -> "RecoveryContext | None":
+        descriptions = {
+            StopReason.PENDING: "The previous run did not record a normal end and may have exited unexpectedly.",
+            StopReason.ABORTED: "The previous run was aborted by the user.",
+            StopReason.ERROR: "The previous run ended with an execution error.",
+        }
+        description = descriptions.get(reason)
+        if description is None:
+            return None
+        return cls(
+            text="[Previous run status]\n"
+            f"{description} Some side effects may have partially completed. "
+            "Check the checkpoint and current workspace state before continuing. "
+            "Do not assume unfinished operations succeeded or failed. "
+            "Follow the user's current instruction."
+        )
+
+
+def set_recovery_context(context: RecoveryContext | None) -> Token[RecoveryContext | None]:
+    return _active_context.set(context)
+
+
+def reset_recovery_context(token: Token[RecoveryContext | None]) -> None:
+    _active_context.reset(token)
+
+
+class RecoveryContextMiddleware(AgentMiddleware):
+    def wrap_model_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        context = _active_context.get()
+        if context is None or not context.armed or context.text is None:
+            return handler(request)
+        original = request.system_message
+        if original is None:
+            system_message = SystemMessage(content=context.text)
+        elif isinstance(original.content, str):
+            system_message = original.model_copy(update={"content": f"{original.content}\n\n{context.text}"})
+        else:
+            system_message = original.model_copy(update={
+                "content": [*original.content, {"type": "text", "text": context.text}],
+            })
+        response = handler(request.override(system_message=system_message))
+        context.text = None
+        return response

agent/middleware/steering.py

@@ -0,0 +1,35 @@
+"""Inject mid-turn steering HumanMessages at model-safe boundaries."""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain.agents.middleware.types import hook_config
+from langchain_core.messages import HumanMessage
+
+from agent.control import RunController
+
+
+class SteeringMiddleware(AgentMiddleware):
+    """Consume one steering message per before_model / after_agent boundary."""
+
+    def __init__(self, controller: RunController) -> None:
+        super().__init__()
+        self._controller = controller
+
+    def before_model(self, state: Any, runtime: Any) -> dict[str, Any] | None:  # noqa: ANN401
+        return self._consume(state)
+
+    @hook_config(can_jump_to=["model"])
+    def after_agent(self, state: Any, runtime: Any) -> dict[str, Any] | None:  # noqa: ANN401
+        update = self._consume(state)
+        if update is None:
+            return None
+        update["jump_to"] = "model"
+        return update
+
+    def _consume(self, state: Any) -> dict[str, Any] | None:  # noqa: ANN401
+        text = self._controller.pop_steering()
+        if text is None:
+            return None
+        return {"messages": [HumanMessage(content=text)]}

agent/middleware/tool_arg_hints.py

@@ -0,0 +1,128 @@
+"""Turn tool argument validation failures into guidance the model can act on.
+
+ToolNode reports pydantic errors verbatim ("Input should be a valid list"), which
+does not tell the model *how* the payload was wrong. Models then resend the same
+arguments with only the prose reworded, and the call fails identically. This
+middleware re-validates the arguments on the error path and replaces the content
+with the offending value, the expectation, and the parameter schema.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import ToolMessage
+from pydantic import BaseModel, ValidationError
+
+
+_MAX_INPUT_CHARS = 160
+_MAX_SCHEMA_CHARS = 2500
+
+_EXPECTATIONS = {
+    "list_type": "必须是原生 JSON 数组，不要把结构序列化成字符串",
+    "dict_type": "必须是原生 JSON 对象，不要把结构序列化成字符串",
+    "string_type": "必须是字符串",
+    "bool_type": "必须是布尔值 true / false",
+    "int_type": "必须是整数",
+    "float_type": "必须是数字",
+    "missing": "必填参数，不能省略",
+    "literal_error": "取值不在允许的枚举内，见下方 schema",
+    "enum": "取值不在允许的枚举内，见下方 schema",
+    "string_pattern_mismatch": "字符串格式不符合要求，见下方 schema",
+    "too_short": "长度不足，见下方 schema",
+    "model_attributes_type": "结构不符合该参数的 schema，见下方 schema",
+    "model_type": "必须是 JSON 对象，见下方 schema",
+}
+
+
+class ToolArgHintMiddleware(AgentMiddleware):
+    """Rewrite argument validation errors so the model fixes the payload instead of resending it."""
+
+    def wrap_tool_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        return _rewrite(request, handler(request))
+
+
+def _rewrite(request: Any, result: Any) -> Any:
+    if not isinstance(result, ToolMessage) or result.status != "error":
+        return result
+    tool = getattr(request, "tool", None)
+    schema = getattr(tool, "tool_call_schema", None)
+    args = (getattr(request, "tool_call", None) or {}).get("args")
+    if not isinstance(schema, type) or not issubclass(schema, BaseModel):
+        return result
+    if not isinstance(args, dict):
+        return result
+    try:
+        schema.model_validate(args)
+    except ValidationError as exc:
+        content = _describe(str(getattr(tool, "name", "") or "tool"), exc, schema)
+    else:
+        # Arguments are valid, so the failure came from the tool body. Leave it alone.
+        return result
+    return ToolMessage(
+        content=content,
+        tool_call_id=result.tool_call_id,
+        name=result.name,
+        status="error",
+    )
+
+
+def _describe(tool_name: str, exc: ValidationError, schema: type[BaseModel]) -> str:
+    lines = [
+        f"参数校验失败，`{tool_name}` 没有执行，也没有产生任何副作用。",
+        "请按下面的说明修正参数后重新调用，不要原样重发同一份参数。",
+        "",
+        "错误：",
+    ]
+    for error in exc.errors():
+        loc = ".".join(str(part) for part in error.get("loc") or ()) or "(root)"
+        value = error.get("input")
+        expectation = _EXPECTATIONS.get(str(error.get("type") or ""))
+        detail = f"- {loc}: 收到 {type(value).__name__}（{error.get('msg')}）"
+        if expectation:
+            detail += f" → {expectation}"
+        lines.append(detail)
+        preview = _preview(value)
+        if preview:
+            lines.append(f"  收到内容：{preview}")
+    lines.extend(["", f"`{tool_name}` 的参数 schema：", _schema_text(schema)])
+    return "\n".join(lines)
+
+
+def _preview(value: Any) -> str:
+    try:
+        text = json.dumps(value, ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        text = str(value)
+    text = text.replace("\n", " ")
+    if len(text) > _MAX_INPUT_CHARS:
+        return f"{text[:_MAX_INPUT_CHARS]}…"
+    return text
+
+
+def _schema_text(schema: type[BaseModel]) -> str:
+    doc = schema.model_json_schema()
+    doc.pop("description", None)
+    text = json.dumps(_without_titles(doc), ensure_ascii=False, separators=(",", ":"))
+    if len(text) > _MAX_SCHEMA_CHARS:
+        return f"{text[:_MAX_SCHEMA_CHARS]}…（schema 已截断）"
+    return text
+
+
+def _without_titles(node: Any) -> Any:
+    # pydantic 给每个字段生成的 "title" 元数据对模型没有信息量，只会挤占提示预算。
+    # properties / $defs 下面的 key 是参数名和模型名，必须原样保留。
+    if isinstance(node, dict):
+        kept: dict[str, Any] = {}
+        for key, value in node.items():
+            if key in ("properties", "$defs", "definitions"):
+                kept[key] = {
+                    name: _without_titles(item) for name, item in value.items()
+                } if isinstance(value, dict) else value
+            elif key != "title":
+                kept[key] = _without_titles(value)
+        return kept
+    if isinstance(node, list):
+        return [_without_titles(item) for item in node]
+    return node

agent/middleware/workspace_filesystem.py

@@ -0,0 +1,38 @@
+"""Filesystem middleware capability check for the workspace shell wrapper."""
+from __future__ import annotations
+
+from deepagents.backends.protocol import BackendProtocol
+from deepagents.middleware.filesystem import FilesystemMiddleware
+
+from agent.sandbox import WorkspaceCompositeBackend
+
+
+class WorkspaceFilesystemMiddleware(FilesystemMiddleware):
+    """Keep the separately registered execute tool visible to the model.
+
+    Deep Agents checks only a CompositeBackend's default route for shell
+    support. Our default route denies file access outside /workspace, while
+    WorkspaceCompositeBackend.execute delegates to the sandbox executor.
+    """
+
+    @property
+    def name(self) -> str:
+        # Deep Agents replaces its built-in middleware by matching this name.
+        return "FilesystemMiddleware"
+
+    def _unsupported_tools_and_execution_state(
+        self, tool_names: set[str | None],
+    ) -> tuple[set[str | None], bool, BackendProtocol | None]:
+        unsupported, execution_active, backend = super()._unsupported_tools_and_execution_state(tool_names)
+        if "execute" in tool_names and isinstance(self.backend, WorkspaceCompositeBackend):
+            unsupported.discard("execute")
+            execution_active = True
+            # Upstream builds its "virtual mounts vs. shell paths" prompt from
+            # the returned backend, judging reachability by the composite's
+            # default route. Our execute shell runs on the executor's
+            # filesystem, where /workspace is the shell root, so returning the
+            # composite would inject a bogus "/workspace is not accessible
+            # from the shell" notice. The executor is not a CompositeBackend,
+            # which makes that prompt empty.
+            backend = self.backend.executor
+        return unsupported, execution_active, backend

agent/middleware/write_operation.py

@@ -0,0 +1,60 @@
+"""Attach the pre-write file state to successful write_file results."""
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from deepagents.backends.protocol import BackendProtocol, LsResult
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+from agent.file_mutation import WriteOperation
+
+
+def _operation(result: LsResult) -> WriteOperation | None:
+    error = result.error or ""
+    if error.endswith(": path_not_found"):
+        return "create"
+    if error.endswith(": not_a_directory"):
+        return "overwrite"
+    return None
+
+
+def _write_path(request: Any) -> str | None:
+    call = getattr(request, "tool_call", None) or {}
+    if call.get("name") != "write_file":
+        return None
+    args = call.get("args")
+    if not isinstance(args, dict) or not isinstance(args.get("file_path"), str):
+        return None
+    return args["file_path"]
+
+
+def _annotate(result: Any, operation: WriteOperation | None) -> Any:
+    if operation is None or not isinstance(result, ToolMessage) or result.status == "error":
+        return result
+    artifact = result.artifact if isinstance(result.artifact, dict) else {}
+    return result.model_copy(update={"artifact": {**artifact, "operation": operation}})
+
+
+class WriteOperationMiddleware(AgentMiddleware):
+    """Classify a write from the backend state immediately before execution."""
+
+    def __init__(self, backend: BackendProtocol) -> None:
+        super().__init__()
+        self._backend = backend
+
+    def wrap_tool_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        path = _write_path(request)
+        try:
+            operation = _operation(self._backend.ls(path)) if path is not None else None
+        except (OSError, RuntimeError, NotImplementedError):
+            operation = None
+        return _annotate(handler(request), operation)
+
+    async def awrap_tool_call(self, request: Any, handler: Callable[[Any], Awaitable[Any]]) -> Any:
+        path = _write_path(request)
+        try:
+            operation = _operation(self._backend.ls(path)) if path is not None else None
+        except (OSError, RuntimeError, NotImplementedError):
+            operation = None
+        return _annotate(await handler(request), operation)

agent/network.py

@@ -0,0 +1,30 @@
+"""Per-execute NETWORK capability (physical gate via Bubblewrap netns)."""
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+_EXECUTE_NETWORK: ContextVar[bool] = ContextVar("deep_agent_execute_network", default=False)
+
+
+def network_requested(args: dict[str, Any] | None) -> bool:
+    """True when a tool call declares the NETWORK capability."""
+    if not args:
+        return False
+    value = args.get("network", False)
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def get_execute_network() -> bool:
+    return bool(_EXECUTE_NETWORK.get())
+
+
+def set_execute_network(enabled: bool):
+    """Set NETWORK for the current tool-call scope. Returns a reset token."""
+    return _EXECUTE_NETWORK.set(bool(enabled))
+
+
+def reset_execute_network(token) -> None:
+    _EXECUTE_NETWORK.reset(token)

agent/permission.py

@@ -0,0 +1,80 @@
+"""Runtime tool-approval policy (ask vs sandboxed allow-all)."""
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from agent.sandbox import ExecutionMode
+
+
+class PermissionMode(StrEnum):
+    """Two-state tool permission policy."""
+
+    ASK = "ask"  # Side-effect tools and every execute pause for approval.
+    ALLOW = "allow"  # Auto-approve all tools; sandbox network open (SANDBOXED only).
+
+
+ASK_INTERRUPT_ON: dict[str, Any] = {
+    "execute": {"allowed_decisions": ["approve", "reject"]},
+    "write_file": True,
+    "edit_file": True,
+    "delete": True,
+}
+
+PERMISSION_ALLOW_WARNING = (
+    "HIGH RISK: Permission mode ALLOW auto-approves every tool call and any "
+    "capabilities it declares (including file writes and deletes), and runs "
+    "every execute with the sandbox network OPEN: full host network access "
+    "(internet, localhost, LAN). There is no per-call confirmation. Only "
+    "enable this if the agent is running in a SANDBOXED backend."
+)
+
+
+def allow_mode_available(execution_mode: ExecutionMode) -> bool:
+    """ALLOW is only valid when the backend is a known isolated sandbox."""
+    return execution_mode is ExecutionMode.SANDBOXED
+
+
+def allow_mode_unavailable_reason(execution_mode: ExecutionMode) -> str:
+    return (
+        "ALLOW is only available when execution mode is SANDBOXED "
+        f"(current: {execution_mode.value})"
+    )
+
+
+def interrupt_on_for_mode(mode: PermissionMode) -> dict[str, Any] | None:
+    """Return create_agent interrupt_on for the mode.
+
+    Empty mapping disables HumanInTheLoopMiddleware tool gates when the factory
+    treats an explicit mapping as a full replacement for the default CONFIRM set.
+    """
+    if mode is PermissionMode.ALLOW:
+        return {}
+    return dict(ASK_INTERRUPT_ON)
+
+
+def permission_mode_from_interrupt_on(interrupt_on: dict[str, Any] | None) -> PermissionMode:
+    return PermissionMode.ALLOW if not interrupt_on else PermissionMode.ASK
+
+
+def parse_permission_mode(value: str) -> PermissionMode | None:
+    key = value.strip().lower().replace("_", "-")
+    aliases = {
+        "ask": PermissionMode.ASK,
+        "confirm": PermissionMode.ASK,
+        "approve": PermissionMode.ASK,
+        "all-approve": PermissionMode.ASK,
+        "allapprove": PermissionMode.ASK,
+        "allow": PermissionMode.ALLOW,
+        "bypass": PermissionMode.ALLOW,
+        "yolo": PermissionMode.ALLOW,
+        "auto": PermissionMode.ALLOW,
+        "all-allow": PermissionMode.ALLOW,
+    }
+    return aliases.get(key)
+
+
+def permission_mode_label(mode: PermissionMode) -> str:
+    if mode is PermissionMode.ALLOW:
+        return "allow (auto-approve all tools; sandbox network OPEN — SANDBOXED only, HIGH RISK)"
+    return "ask (side-effect tools and every execute require approval)"