tools.stargazer_shadowban module

Stargazer shadow ban tool — start the shadow ban pipeline on a user.

Star calls this when she wants to apply a gradual punishment pipeline. Unlike stargazer_ban (which hard-flips a bit), this starts the 4-phase degradation curve: Latency → Drops → Fake 503 → Blackout, culminating in the STARGAZER_USE bit flip at progress 1.0.

Star passes target_user_id and an optional duration_days (default 15). If auto_lift_days is provided, a background task will automatically lift the shadow ban after that many days — the pipeline effects stop and the user is restored silently.

Privilege model

  • Self-ban (target_user_id == ctx.user_id): always permitted. This is the primary path for Star’s autonomous punitive action — the conversational user and the target are one and the same.

  • Cross-user ban (target_user_id != ctx.user_id): requires the SHADOW_BAN_ADMIN bit (bit 14) in the caller’s global privilege mask. Configured admins are implicitly granted this via ALL_BITS.

  • Admin targets: always refused regardless of caller privileges.

async tools.stargazer_shadowban.run(target_user_id, reason='', duration_days=15.0, auto_lift_days=None, ctx=None)[source]

Start the multi-phase shadow-ban degradation pipeline against a user.

This is the stargazer_shadowban tool entry point. Unlike the hard bit-flip of stargazer_ban, it begins an invisible-to-the-target punishment curve (latency, then drops, then fake errors, then blackout) that ends in a permanent STARGAZER_USE revocation at progress 1.0 unless an auto_lift_days timer is set. Self-bans (target == caller) are always allowed for autonomous punitive action; banning anyone else requires the caller to hold the SHADOW_BAN_ADMIN privilege, and admins can never be targeted.

Enforces privileges against Redis via has_privilege / _is_admin (with PRIVILEGES from tools.alter_privileges), then constructs a ShadowBanManager (from patience_engine) over ctx.redis, ctx.kg_manager, and ctx.config and calls get_ban / get_progress to reject duplicates and start_ban to persist the new pipeline (which writes the manager’s shadow-ban state into Redis and the knowledge graph). When auto_lift_days is positive it schedules _auto_lift_after() as a detached asyncio task. The action is logged. As a tool it is dispatched by name through the registry: tool_loader.py registers this module’s run as the handler for stargazer_shadowban and the inference worker invokes it on the matching tool call; it has no in-repo direct callers.

Parameters:

  • target_user_id (str) – The user to shadow ban (whitespace-trimmed).

  • reason (str) – Optional free-text reason, logged and echoed in the result.

  • duration_days (float) – Length of the degradation pipeline in days (default 15, clamped to (0, 365]); shorter durations escalate faster.

  • auto_lift_days (float | None) – If set and positive, schedule an automatic lift after this many days via _auto_lift_after(); if omitted the pipeline runs to a permanent ban.

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

Returns:

A human-readable result — a confirmation describing the pipeline and any scheduled auto-lift, or an error string when context is missing, the target is empty, Redis is unavailable, privileges are insufficient, the target is an admin, the durations are invalid, the subsystem is unavailable, or the user is already shadow banned.

Return type:

str