From faa6f5f495cd9bf33ef751284e25c7cf5130a95a Mon Sep 17 00:00:00 2001
From: LIghtJUNction <lightjunction.me@gmail.com>
Date: Tue, 24 Mar 2026 16:09:26 +0800
Subject: [PATCH] docs: add abp-runtime-status-plugin spec and specs

---
 .../changes/abp-runtime-status-plugin/spec.md | 113 ++++++++++++++++++
 openspec/specs/runtime-status-star/spec.md    |  39 ++++++
 2 files changed, 152 insertions(+)
 create mode 100644 openspec/changes/abp-runtime-status-plugin/spec.md
 create mode 100644 openspec/specs/runtime-status-star/spec.md

diff --git a/openspec/changes/abp-runtime-status-plugin/spec.md b/openspec/changes/abp-runtime-status-plugin/spec.md
new file mode 100644
index 000000000..e397565d3
--- /dev/null
+++ b/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.
diff --git a/openspec/specs/runtime-status-star/spec.md b/openspec/specs/runtime-status-star/spec.md
new file mode 100644
index 000000000..3f9221b04
--- /dev/null
+++ b/openspec/specs/runtime-status-star/spec.md
@@ -0,0 +1,39 @@
+# Runtime Status Star Specification
+
+## ADDED Requirements
+
+### Requirement: RuntimeStatusStar provides diagnostic tools
+
+The RuntimeStatusStar SHALL provide callable tools that expose core runtime internal state for diagnostic purposes.
+
+#### Scenario: Get runtime status
+- **WHEN** ABP client calls `get_runtime_status` tool
+- **THEN** returns `{"running": bool, "uptime_seconds": float}`
+
+#### Scenario: Get protocol status
+- **WHEN** ABP client calls `get_protocol_status` tool
+- **THEN** returns status of each protocol client (lsp, mcp, acp, abp)
+
+#### Scenario: Get star registry
+- **WHEN** ABP client calls `get_star_registry` tool
+- **THEN** returns list of registered star names
+
+#### Scenario: Get stats
+- **WHEN** ABP client calls `get_stats` tool
+- **THEN** returns runtime statistics including message counts
+
+### Requirement: Auto-registration with orchestrator
+
+The RuntimeStatusStar SHALL be automatically registered with the orchestrator on initialization.
+
+#### Scenario: Orchestrator initialization
+- **WHEN** AstrbotOrchestrator is created
+- **THEN** RuntimeStatusStar instance is created and registered with name "runtime-status-star"
+
+### Requirement: Error handling
+
+The RuntimeStatusStar tools SHALL handle errors gracefully without exposing internal exceptions.
+
+#### Scenario: Orchestrator unavailable
+- **WHEN** orchestrator reference is None
+- **THEN** returns appropriate error message instead of raising exception