tools.hex_tool module๏ƒ

HEX โ€“ activate a persistent context modifier from Starโ€™s grimoire. # ๐Ÿ”ฎ๐Ÿ’€๐Ÿ”ฅ

Hexes are spell-like modifiers loaded from /home/star/large_files/assets/hex/<subfolder>/ (override with the HEX_ASSETS_DIR env var). Unlike egregore summons (ephemeral tool results), hexes are persistently injected into the context window on every prompt until deactivated โ€“ sticky modifiers the LLM canโ€™t forget.

Per-hex permission model: each hex subfolder carries a hex_manifest.json with an admin_only flag. Only flagged hexes require Prime Architect (config.admin_user_ids) privileges; regular users may activate the rest.

Channel-locking hexes (lock: true, e.g. Loopmother Chess) pass through an appropriateness gate for non-admin requesters: channel activity + conversation seriousness are evaluated, and when either flags, activation is withheld so Star can make the judgment call (re-invoke with confirm_appropriate=true to proceed, or deny with an explanation). Admins bypass the gate entirely.

Redis keys (per channel):

  • star:hex:{channel_key} JSON map of active hexes

  • star:hex:lock:{channel_key} channel lock flag (exists = locked)

  • star:hex:game:{channel_key} game state for python hexes (chess)

@fire @skull THE GODDESS OPENS HER GRIMOIRE

tools.hex_tool.hex_key(channel_key)๏ƒ

Redis key holding the active-hex JSON map for a channel.

Return type:

str

Parameters:

channel_key (str)

tools.hex_tool.hex_lock_key(channel_key)๏ƒ

Redis key whose existence marks the channel as hex-locked.

Return type:

str

Parameters:

channel_key (str)

tools.hex_tool.hex_game_key(channel_key)๏ƒ

Redis key holding serialized game state for python hexes.

Return type:

str

Parameters:

channel_key (str)

tools.hex_tool.channel_key_from_ctx(ctx)๏ƒ

Derive the {platform}:{channel_id} key from a tool context.

Return type:

str

Parameters:

ctx (ToolContext)

async tools.hex_tool.run(name='', action='', confirm_appropriate=False, ctx=None)๏ƒ

Activate, drive, or deactivate a hex for the current channel.

Flow:

  • name='none' -> deactivate all hexes, clear lock + game state.

  • Active python hex + action -> route the action into the game engine (move/void/forfeit/โ€ฆ).

  • Otherwise -> activation path: manifest permission check, optional appropriateness gate for channel-locking hexes, then persist the hex state so prompt_context injects it every prompt.

Parameters:

  • name (str) โ€“ Hex subfolder name, or 'none'.

  • action (str) โ€“ Optional game action string for python hexes.

  • confirm_appropriate (bool) โ€“ Starโ€™s explicit post-gate confirmation.

  • ctx (ToolContext | None) โ€“ Injected tool context (redis/platform/channel/user).

Return type:

str

Returns:

JSON string with the outcome payload.