tools.stargazer_ban module

Stargazer ban tool — revoke STARGAZER_USE for the interacting user.

Star calls this when she decides a user should lose access. The user_id parameter is exposed to the LLM for UX but is always overridden by ctx.user_id to prevent the model from being tricked into banning someone other than the person she’s talking to.

An optional duration_days makes the ban temporary: a background asyncio task restores the bit after the timer expires. Without it the ban is permanent until an admin manually grants the bit back.

async tools.stargazer_ban.run(user_id, reason='', duration_days=None, ctx=None)[source]

Revoke the global STARGAZER_USE privilege bit for the interacting user.

This is the stargazer_ban tool entry point. It is the LLM’s lever for cutting off a user it is conversing with: it clears bit 63 in the user’s GLOBAL privilege mask so the bot stops serving them. The model-supplied user_id is intentionally ignored in favor of ctx.user_id so the ban can never be redirected at a third party, and admins are refused outright.

Reads and writes Redis directly: it fetches the current mask via get_user_privileges and persists the bit-cleared mask with redis.set under _redis_key (both from tools.alter_privileges), and uses _is_admin from the same module to enforce the admin exemption. When a positive duration_days is given it schedules _restore_after() as a detached asyncio task to auto-lift the ban; otherwise the ban is permanent. All actions are logged. As a tool, it is dispatched by name through the tool registry: tool_loader.py registers this module’s run as the handler for stargazer_ban and the inference worker invokes it when the LLM emits that tool call; it has no in-repo direct callers.

Parameters:

  • user_id (str) – Cosmetic only — the user the model thinks it is banning. The real target is always ctx.user_id.

  • reason (str) – Optional free-text reason, included in the log line and the returned confirmation.

  • duration_days (float | None) – Optional ban length in days (fractional allowed). If set and positive, the ban auto-expires via _restore_after(); otherwise it is permanent.

  • ctx (ToolContext | None) – The tool context supplying user_id, redis, and config.

Returns:

A human-readable result — a confirmation with the old/new mask, or an error string when context, user_id, or Redis is missing, when the target is an admin, or when the user is already banned.

Return type:

str