"""Pause the active Lyria music stream in a Discord voice channel."""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from tool_context import ToolContext
logger = logging.getLogger(__name__)
TOOL_NAME = "pause_music"
TOOL_DESCRIPTION = (
"Pause the currently playing Lyria music stream in a Discord voice channel. "
"Use resume_music to resume. Requires active music session."
)
TOOL_PARAMETERS = {
"type": "object",
"properties": {
"guild_id": {"type": "string", "description": "Discord server (guild) ID."},
},
"required": ["guild_id"],
}
[docs]
async def run(
guild_id: str,
ctx: "ToolContext | None" = None,
) -> str:
"""Pause the active Lyria RealTime music stream for a guild.
Implements the ``pause_music`` tool. It does not generate audio itself;
instead it resolves the Discord client and the Lyria service hanging off
the platform adapter and asks Lyria to suspend the in-progress generation
so it can later be resumed with ``resume_music`` without tearing down the
voice connection.
Validates that a Discord-capable context was supplied (``ctx.adapter``),
fetches the live ``discord.Client`` via ``tools._discord_helpers.get_discord_client``
(returning that helper's error string if the client is unavailable), coerces
``guild_id`` to an int, and then delegates to
``ctx.adapter.lyria_service.pause``, whose return string is passed straight
back to the model. It is registered and dispatched dynamically by
``tool_loader.py`` as the module-level ``run`` handler; no in-repo callers
invoke it directly outside of tests.
Args:
guild_id: Discord server (guild) ID as a string; rejected if it cannot
be parsed as an integer.
ctx: The tool execution context. Must expose a non-``None`` ``adapter``
with a ``lyria_service``; otherwise an error string is returned.
Returns:
str: The Lyria service's status message on success, or an ``Error:``
prefixed string when the adapter is missing, the Discord client is
unavailable, or ``guild_id`` is invalid.
"""
if ctx is None or not hasattr(ctx, "adapter") or ctx.adapter is None:
return "Error: Discord adapter (ctx.adapter) is required."
from tools._discord_helpers import get_discord_client
client = get_discord_client(ctx)
if isinstance(client, str):
return client
lyria = ctx.adapter.lyria_service
try:
guild_id_int = int(guild_id)
except (ValueError, TypeError):
return "Error: Invalid guild_id."
return await lyria.pause(guild_id_int)