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

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:

{
  "running": true,
  "uptime_seconds": 12345.67
}

2. get_protocol_status

Returns the connection state of each protocol client.

Arguments: None

Returns:

{
  "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:

{
  "stars": ["runtime-status-star", "star-1", "star-2"]
}

4. get_stats

Returns runtime statistics and metrics.

Arguments: None

Returns:

{
  "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__():

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:

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.