docs: add abp-runtime-status-plugin spec and specs

openspec/changes/abp-runtime-status-plugin/spec.md

@@ -0,0 +1,113 @@
+# RuntimeStatusStar Specification
+
+## Overview
+
+RuntimeStatusStar is an internal ABP (AstrBot Protocol) star plugin that exposes runtime state information via callable tools. It provides diagnostic capabilities for monitoring the AstrBot core runtime health.
+
+## Tool Interface
+
+### Tools Exposed
+
+All tools follow the ABP tool calling convention via `call_tool(tool_name, arguments)`.
+
+#### 1. get_runtime_status
+
+Returns the current runtime state.
+
+**Arguments:** None
+
+**Returns:**
+```json
+{
+  "running": true,
+  "uptime_seconds": 12345.67
+}
+```
+
+#### 2. get_protocol_status
+
+Returns the connection state of each protocol client.
+
+**Arguments:** None
+
+**Returns:**
+```json
+{
+  "lsp": {"connected": true, "name": "lsp-client"},
+  "mcp": {"connected": false, "name": "mcp-client"},
+  "acp": {"connected": true, "name": "acp-client"},
+  "abp": {"connected": true, "name": "abp-client"}
+}
+```
+
+#### 3. get_star_registry
+
+Returns the list of registered star names.
+
+**Arguments:** None
+
+**Returns:**
+```json
+{
+  "stars": ["runtime-status-star", "star-1", "star-2"]
+}
+```
+
+#### 4. get_stats
+
+Returns runtime statistics and metrics.
+
+**Arguments:** None
+
+**Returns:**
+```json
+{
+  "total_messages": 100,
+  "last_activity": "2024-01-01T00:00:00Z"
+}
+```
+
+## Architecture
+
+### Component Hierarchy
+
+```
+AstrbotOrchestrator
+  └── RuntimeStatusStar (auto-registered)
+        └── Tools: get_runtime_status, get_protocol_status, get_star_registry, get_stats
+```
+
+### Auto-Registration
+
+RuntimeStatusStar is instantiated and registered in `AstrbotOrchestrator.__init__()`:
+
+```python
+from astrbot._internal.stars.runtime_status_star import RuntimeStatusStar
+
+class AstrbotOrchestrator:
+    def __init__(self):
+        self._stars: dict[str, Star] = {}
+        # Auto-register RuntimeStatusStar
+        self._runtime_status_star = RuntimeStatusStar(self)
+        self._stars["runtime-status-star"] = self._runtime_status_star
+```
+
+### Orchestrator Reference
+
+RuntimeStatusStar holds a reference to the orchestrator to query state:
+
+```python
+class RuntimeStatusStar(Star):
+    def __init__(self, orchestrator: AstrbotOrchestrator):
+        self._orchestrator = orchestrator
+```
+
+## Implementation Notes
+
+1. **Thread Safety:** The orchestrator may be accessed from multiple contexts. All state queries should be read-only.
+
+2. **Latency:** Tool calls should return immediately without blocking. No polling or long-running operations.
+
+3. **Error Handling:** If any status query fails, return an error message rather than raising an exception.
+
+4. **Future Extensibility:** Additional stats can be added by extending the `get_stats` tool response structure.