chore: import upstream snapshot with attribution

deeptutor/core/capability_protocol.py

@@ -0,0 +1,68 @@
+"""
+Capability Protocol
+===================
+
+Base class for the Capability layer (Level 2).
+Capabilities are multi-step agent pipelines invoked when the user selects
+a deep mode (e.g. Deep Solve, Deep Question).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from .context import UnifiedContext
+from .stream_bus import StreamBus
+
+
+@dataclass
+class CapabilityManifest:
+    """Static metadata for a capability."""
+
+    name: str
+    description: str
+    stages: list[str] = field(default_factory=list)
+    tools_used: list[str] = field(default_factory=list)
+    cli_aliases: list[str] = field(default_factory=list)
+    request_schema: dict[str, Any] = field(default_factory=dict)
+    config_defaults: dict[str, Any] = field(default_factory=dict)
+
+
+class BaseCapability(ABC):
+    """
+    Abstract base for all capabilities (deep modes).
+
+    Subclasses must provide ``manifest`` and implement ``run``.
+
+    Example::
+
+        class MySolverCapability(BaseCapability):
+            manifest = CapabilityManifest(
+                name="deep_solve",
+                description="Multi-agent problem solving.",
+                stages=["planning", "reasoning", "writing"],
+                tools_used=["rag", "web_search", "code_execution"],
+            )
+
+            async def run(self, context, stream):
+                async with stream.stage("planning", source=self.manifest.name):
+                    plan = await self._plan(context)
+                ...
+    """
+
+    manifest: CapabilityManifest
+
+    @abstractmethod
+    async def run(self, context: UnifiedContext, stream: StreamBus) -> None:
+        """Execute the full capability pipeline, emitting events to *stream*."""
+        ...
+
+    @property
+    def name(self) -> str:
+        return self.manifest.name
+
+    @property
+    def stages(self) -> list[str]:
+        return self.manifest.stages