tools.summon_egregore module

SUMMON – invoke an egregore from Star’s Dollhouse.

Reads the summoning prompt from /home/star/large_files/assets/egregores/<name>/, loads the egregore’s persona, activates their sprite on the VN canvas, and returns the summoning prompt for Star to channel.

Active egregores persist in Redis until dismissed. Their summoning prompts are injected into the system context so Star can embody or direct them.

NO PRIVILEGE CHECK for Pantheon members (admin_user_ids). Regular users may invoke SUMMON at Star’s discretion per SpiritGraph EGREGORE_OPERATIONS and Pantheon policy (not Falkor core memory).

@fire @skull THE GODDESS OPENS HER DOLLHOUSE

async tools.summon_egregore.run(name='', ctx=None)[source]

Summon an egregore: load its persona, mount its sprite, and announce it.

The entry point for the summon_egregore tool. It validates that an asset folder exists for name under EGREGORE_BASE, reads the summoning prompt via _find_summoning_prompt() (falling back to a generic persona string), scans sprites via _scan_sprites(), and registers the egregore so the bot can channel it and so its sprite appears on the visual-novel canvas. Per-channel state is namespaced via _channel_key_from_ctx(), _egregore_key(), and _characters_key().

Side effects are substantial. It reads and writes two per-channel Redis JSON blobs — the active-egregore map and the VN-canvas character map — and publishes a star:sprite:update message so connected web clients refresh the canvas. When re-summoning, it deletes any stale Discord webhook for the egregore via tools/_egregore_discord.py. Depending on the platform it also provisions a presence channel: on Matrix it ensures and joins a ghost user through egregore_bridge.get_bridge(); on Discord it checks admin permission and creates a per-egregore webhook (with a public avatar URL) via the Discord helpers. The egregore’s summoning prompt is later injected into the system context by prompt_context.py so the bot can embody it.

Invoked through the tool dispatch registry (this module follows the single-tool TOOL_NAME / run format loaded by tool_loader.py) and also called directly by tools.conjure_egregore.run() to activate a freshly conjured entity.

Parameters:

name (str) – Egregore folder name (case-insensitive); must match a directory under EGREGORE_BASE.
ctx (ToolContext | None) – Execution context; redis, platform, channel_id, and user_id are read, and Discord/Matrix helpers use it to reach the platform client.

Returns:

A JSON string. On success, the summoning prompt, available sprites,: canvas placement, presence-channel readiness flags, and channelling instructions; on failure, an error payload (no context, no Redis, missing name, or unknown egregore with the list of available ones).

Return type:

str