feat: add create_deerflow_agent SDK entry point (Phase 1) (#1203)

backend/packages/harness/deerflow/agents/features.py

@@ -0,0 +1,62 @@
+"""Declarative feature flags and middleware positioning for create_deerflow_agent.
+
+Pure data classes and decorators — no I/O, no side effects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from langchain.agents.middleware import AgentMiddleware
+
+
+@dataclass
+class RuntimeFeatures:
+    """Declarative feature flags for ``create_deerflow_agent``.
+
+    Most features accept:
+    - ``True``: use the built-in default middleware
+    - ``False``: disable
+    - An ``AgentMiddleware`` instance: use this custom implementation instead
+
+    ``summarization`` and ``guardrail`` have no built-in default — they only
+    accept ``False`` (disable) or an ``AgentMiddleware`` instance (custom).
+    """
+
+    sandbox: bool | AgentMiddleware = True
+    memory: bool | AgentMiddleware = False
+    summarization: Literal[False] | AgentMiddleware = False
+    subagent: bool | AgentMiddleware = False
+    vision: bool | AgentMiddleware = False
+    auto_title: bool | AgentMiddleware = False
+    guardrail: Literal[False] | AgentMiddleware = False
+
+
+# ---------------------------------------------------------------------------
+# Middleware positioning decorators
+# ---------------------------------------------------------------------------
+
+
+def Next(anchor: type[AgentMiddleware]):
+    """Declare this middleware should be placed after *anchor* in the chain."""
+    if not (isinstance(anchor, type) and issubclass(anchor, AgentMiddleware)):
+        raise TypeError(f"@Next expects an AgentMiddleware subclass, got {anchor!r}")
+
+    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
+        cls._next_anchor = anchor  # type: ignore[attr-defined]
+        return cls
+
+    return decorator
+
+
+def Prev(anchor: type[AgentMiddleware]):
+    """Declare this middleware should be placed before *anchor* in the chain."""
+    if not (isinstance(anchor, type) and issubclass(anchor, AgentMiddleware)):
+        raise TypeError(f"@Prev expects an AgentMiddleware subclass, got {anchor!r}")
+
+    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
+        cls._prev_anchor = anchor  # type: ignore[attr-defined]
+        return cls
+
+    return decorator