feat(openspec): add abp-runtime-status-plugin change proposal

openspec/changes/abp-runtime-status-plugin/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-23

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

@@ -0,0 +1,40 @@
+## Context
+
+The AstrBot core runtime (`_internal` package) manages LSP, MCP, ACP, and ABP protocol clients. Currently there is no way to query the internal state of these components from outside the runtime.
+
+The ABP (AstrBot Protocol) is designed for in-process star communication. By creating a RuntimeStatusStar plugin, we can expose runtime state via ABP tools.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create a RuntimeStatusStar that registers with the orchestrator via ABP
+- Expose tools: get_runtime_status, get_protocol_status, get_star_registry, get_stats
+- Use anyio for async operations as per project standard
+
+**Non-Goals:**
+- Not implementing remote ACP/LSP connections (separate concern)
+- Not creating a dashboard UI (future work)
+- Not modifying existing protocol client implementations
+
+## Decisions
+
+1. **Star Interface**: Use the existing `Star` base class from `astrbot._internal.stars.base`
+   - Each star must implement `call_tool(tool_name, arguments)` method
+   - Stars are registered with the orchestrator via `register_star(name, star_instance)`
+
+2. **Tool Exposure**: Expose runtime status as ABP-callable tools
+   - `get_runtime_status`: Returns `{running: bool, uptime_seconds: float}`
+   - `get_protocol_status`: Returns status of each protocol client
+   - `get_star_registry`: Returns list of registered star names
+   - `get_stats`: Returns message counts, last activity, etc.
+
+3. **Auto-registration**: Register RuntimeStatusStar in orchestrator.__init__
+   - This ensures it's available immediately when runtime starts
+
+## Risks / Trade-offs
+
+- **Risk**: Runtime status might be sensitive information
+  - **Mitigation**: Initially only expose basic stats; add auth later if needed
+
+- **Trade-off**: Polling vs push model for stats
+  - Decision: Use polling (pull) via ABP call_tool for simplicity

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

@@ -0,0 +1,27 @@
+## Why
+
+Currently the core runtime (_internal package) has no way to expose its internal state (protocol client status, star registry, message counts, etc.) to external consumers. We need an ABP plugin that exposes runtime status as tools that can be called via the ABP protocol.
+
+## What Changes
+
+- Create an ABP plugin (`RuntimeStatusStar`) that registers with the orchestrator via ABP
+- Expose runtime status as tools callable via ABP protocol:
+  - `get_runtime_status`: Returns overall runtime state
+  - `get_protocol_status`: Returns LSP, MCP, ACP, ABP client states
+  - `get_star_registry`: Returns list of registered stars
+  - `get_stats`: Returns message counts, uptime, etc.
+- Plugin implements the Star interface required by ABP
+
+## Capabilities
+
+### New Capabilities
+- `runtime-status-star`: ABP plugin that exposes core runtime internal state as callable tools
+
+### Modified Capabilities
+- (none)
+
+## Impact
+
+- New file: `astrbot/_internal/stars/runtime_status_star.py`
+- Modifies: `astrbot/_internal/runtime/orchestrator.py` to register the star
+- ABP protocol now can query runtime internals

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

@@ -0,0 +1,32 @@
+## 1. Create Stars Directory
+
+- [ ] 1.1 Create `astrbot/_internal/stars/` directory
+- [ ] 1.2 Create `__init__.py` with exports
+
+## 2. Implement RuntimeStatusStar
+
+- [ ] 2.1 Create `runtime_status_star.py` with RuntimeStatusStar class
+- [ ] 2.2 Implement `call_tool` method with tools:
+  - `get_runtime_status`: Returns running state and uptime
+  - `get_protocol_status`: Returns LSP, MCP, ACP, ABP status
+  - `get_star_registry`: Returns registered star names
+  - `get_stats`: Returns message counts and metrics
+
+## 3. Register Star with Orchestrator
+
+- [ ] 3.1 Import RuntimeStatusStar in orchestrator
+- [ ] 3.2 Register star instance in orchestrator.__init__
+
+## 4. Write Tests
+
+- [ ] 4.1 Create `tests/unit/test_runtime_status_star.py`
+- [ ] 4.2 Test get_runtime_status tool
+- [ ] 4.3 Test get_protocol_status tool
+- [ ] 4.4 Test get_star_registry tool
+- [ ] 4.5 Test orchestrator auto-registers the star
+
+## 5. Verification
+
+- [ ] 5.1 Run ruff check
+- [ ] 5.2 Run uvx ty check
+- [ ] 5.3 Run pytest tests/unit/test_runtime_status_star.py