tool_context

Shared context object passed to tools that need platform access.

Tools opt-in to receiving context by declaring a ctx parameter in their run() signature. The ToolRegistry inspects the handler at call-time and injects the context automatically – the LLM never sees or fills this parameter.

class tool_context.ToolContext(platform='', channel_id='', user_id='', user_name='', guild_id='', adapter=None, message_id='', config=None, redis=None, message_cache=None, kg_manager=None, task_manager=None, threadweave=None, tool_registry=None, conversation_manager=None, openrouter=None, all_adapters=<factory>, adapters_by_name=<factory>, injected_tools=None, sent_files=<factory>)[source]

Bases: object

Runtime context injected into tool handlers that request it.

Parameters:
platform: str = ''

Short identifier for the originating platform ("discord", "matrix", …).

channel_id: str = ''

Platform-specific channel / room identifier.

user_id: str = ''

Platform-specific sender identifier.

user_name: str = ''

Human-readable display name of the sender.

guild_id: str = ''

Discord-specific guild (server) ID. Empty on non-Discord platforms.

adapter: PlatformAdapter | None = None

The PlatformAdapter instance for the originating platform.

For Discord this is a DiscordPlatform whose .client property exposes the underlying discord.Client.

message_id: str = ''

Platform-specific ID of the message that triggered this response.

config: Config | None = None

Global bot Config. Gives tools access to redis_url, model, and other settings.

redis: Any = None

Shared async Redis client (redis.asyncio.Redis).

None when Redis is not configured. Tools should guard access with an if ctx.redis is not None check.

message_cache: MessageCache | None = None

Shared MessageCache instance for retrieving cached messages as CachedMessage objects.

None when Redis is not configured.

kg_manager: KnowledgeGraphManager | None = None

Shared KnowledgeGraphManager for the knowledge graph system.

None when Redis is not configured.

task_manager: TaskManager | None = None

Shared TaskManager for checking background task results. Injected by the message processor so tools like check_task can access it.

threadweave: ThreadweaveManager | None = None

Shared ThreadweaveManager for the Threadweave persistent knowledge system (DNA Vault, Persistent Weave, Shadow Memory).

None when Redis is not configured.

tool_registry: ToolRegistry | None = None

The live ToolRegistry that holds all loaded tools.

Allows meta-tools like list_all_tools and reload_tools to inspect or modify the running tool set.

conversation_manager: ConversationManager | None = None

Shared ConversationManager for per-channel conversation histories.

Allows tools to read or manipulate the in-memory context window for any channel.

openrouter: Any = None

The OpenRouterClient instance for the current session.

Allows tools like extend_tool_loop to adjust the tool-calling loop parameters at runtime.

all_adapters: list[Any]

All running PlatformAdapter instances.

Allows cross-platform tools (e.g. list_active_servers) to query every connected platform, not just the one that triggered the current message.

adapters_by_name: dict[str, Any]

All platform adapters keyed by name (e.g. "discord", "discord-self", "matrix").

Allows tools to look up a specific adapter directly:

selfbot = ctx.adapters_by_name.get("discord-self")
injected_tools: list[str] | None = None

Tool names requested for injection by request_tool_injection.

Populated at runtime by tool handlers; the chat() loop in OpenRouterClient checks this after each round and merges any new names into the active tool list.

When several tools run in the same model round they share this ToolContext and execute concurrently via asyncio.gather. Use only atomic updates (e.g. list.append); avoid read-modify-write races on the same list without coordination.

sent_files: list[dict[str, Any]]

Media files sent to the channel during tool execution.

Each entry has keys: data (raw bytes), filename (str), mimetype (str), and optionally file_url (str). After the LLM call, the message processor converts these into real multimodal content parts (image_url, input_audio, etc.) via media_to_content_parts() and appends them to conversation history so the bot can see its own visual and audio outputs on subsequent turns.

Parallel tools in one LLM round share this list; appends are safe, but do not assume ordering of entries matches tool-call order unless you serialize tool execution.