intellicrack.core.tools

Tool registry for managing tool bridges.

This module provides a registry for tool bridges that handles initialization, availability checking, and tool schema generation for LLM function calling.

ExternalToolExecutor

Signature an external namespace’s executor must satisfy.

It receives the canonical dotted function name and the parsed arguments, and returns whatever the tool produced – a plain JSON-compatible value for a simple tool, or a ToolOutput for one whose output is more than text or that can report its own failure. A call that cannot produce any result raises ToolError.

alias of Callable[[str, dict[str, Any]], Awaitable[object]]

ExternalDefinitionProvider

Signature an external namespace’s definition provider must satisfy.

Called every time the registry is asked what tools exist, so a source whose catalog changes at runtime – a server that added a tool, or one the operator just turned off – is reflected on the next turn without re-registering.

alias of Callable[[], list[ToolDefinition]]

class ExternalToolRegistry[source]

Bases: object

Namespaces served by tool executors outside Intellicrack’s own bridges.

The wire contract for externally-sourced tools – raw JSON Schema, multi-part results, reversible wire names – is complete without any particular source of such tools, so this registry ships now and stays empty until something registers into it. An MCP client is the obvious first tenant.

Bridge namespaces are refused at registration rather than shadowed at dispatch, so the failure is a clear error at the point of the mistake instead of a bridge silently stopping working.

__init__()[source]

Initialize an empty external-tool registry.

Return type:: None

register(namespace, executor, *, definitions=None)[source]

Register an executor, and optionally a definition provider, for one namespace.

Parameters:

namespace (str) – The namespace the executor serves, e.g. mcp-files.
executor (Callable[[str, dict[str, Any]], Awaitable[object]]) – Awaitable callable invoked with the canonical dotted function name and the parsed arguments.
definitions (Callable[[], list[ToolDefinition]] | None) – Callable returning this namespace’s tool definitions, consulted every time the registry is asked what exists. A namespace registered without one can still be dispatched to, it is simply never advertised.

Raises:

ToolError – If the namespace is empty, malformed, or reserved for an Intellicrack bridge.

Return type:

None

unregister(namespace)[source]

Remove an external namespace’s executor and definition provider.

Parameters:: namespace (str) – The namespace to remove.
Returns:: True when an executor was removed.
Return type:: bool

definitions()[source]

Collect the tool definitions every registered namespace advertises.

Each provider is isolated: one that raises contributes nothing and the rest still report, so a single unreachable server cannot empty the catalog and leave the model with no tools at all.

Returns:: Definitions in registration order.
Return type:: list[ToolDefinition]

get(namespace)[source]

Look up the executor serving a namespace.

Parameters:: namespace (str) – The namespace to resolve.
Returns:: The executor, or None when the namespace is not registered.
Return type:: ExternalToolExecutor | None

namespaces()[source]

List every registered external namespace.

Returns:: Registered namespaces, in registration order.
Return type:: list[str]

class ToolStatus[source]

Bases: object

Status of a registered tool.

Variables:

name (ToolName) – Identifier of the tool.
available (bool) – Whether the tool is available on the system.
connected (bool) – Whether the tool is currently connected.
version (str | None) – Tool version if known.
path (Path | None) – Installation path if known.
error (str | None) – Last error if any.

name: ToolName

available: bool

connected: bool

version: str | None = None

path: Path | None = None

error: str | None = None

__init__(name, available, connected, version=None, path=None, error=None)

Parameters:

name (ToolName)
available (bool)
connected (bool)
version (str | None)
path (Path | None)
error (str | None)

Return type:

None

class ToolRegistry[source]

Bases: object

Registry for tool bridges.

Manages initialization, availability, and provides unified access to all tool bridges.

__init__(tools_dir)[source]

Initialize the ToolRegistry with a tools directory.

Parameters:: tools_dir (Path) – Directory for tool installations.
Return type:: None

property external_tools: ExternalToolRegistry

The registry of namespaces served outside Intellicrack’s bridges.

Returns:: The registry a tool source registers into.
Return type:: ExternalToolRegistry

set_session(session)[source]

Attach (or detach) the active session for every registered bridge.

Propagates the supplied session to every bridge so each bridge’s lifecycle transitions (connect, attach, error, detach) flow into the session’s tool_states registry. Newly registered bridges added via register_bridge() inherit the current session automatically.

Parameters:: session (Session | None) – The active Session to publish state into, or None to detach all bridges from any previously attached session.
Return type:: None

property tools_directory: Path

The tools directory.

Returns:: Path to tools directory.
Return type:: Path

async initialize()[source]

Initialize all tool bridges.

Creates bridge instances for all supported tools.

Return type:: None

async initialize_tool(name, port=None)[source]

Initialize a specific tool.

Finds or installs the tool and initializes its bridge.

Parameters:

name (ToolName) – Tool to initialize.
port (int | None) – Network port for bridge communication if applicable.

Returns:

True if initialization succeeded.

Return type:

bool

async shutdown()[source]

Shutdown all tool bridges.

Clears self._bridges after every bridge has been shut down so a subsequent call to initialize() rebuilds the registry from scratch instead of reusing closed bridge instances. Without this, callers observing _bridges after shutdown would see references to bridges whose underlying tool processes have been terminated.

Return type:: None

get(name)[source]

Get a tool bridge by name.

Parameters:: name (ToolName) – Tool name.
Returns:: Tool bridge or None if not registered.
Return type:: ToolBridgeBase | None

register_bridge(name, bridge)[source]

Register or replace a tool bridge.

Allows callers to plug in a pre-built bridge supplied by an embedding application or a test harness without going through initialize(). Replaces any existing bridge registered under the same name and logs the swap so the change is auditable.

Parameters:

name (ToolName) – Tool name to register the bridge under.
bridge (ToolBridgeBase) – Bridge instance to register.

Return type:

None

get_process_bridge()[source]

Get the process control bridge.

Returns:: ProcessBridge instance.
Return type:: ProcessBridge
Raises:: ToolError – If bridge not available.

get_frida_bridge()[source]

Get the Frida instrumentation bridge.

Returns:: FridaBridge instance.
Return type:: FridaBridge
Raises:: ToolError – If bridge not available.

get_ghidra_bridge()[source]

Get the Ghidra analysis bridge.

Returns:: GhidraBridge instance.
Return type:: GhidraBridge
Raises:: ToolError – If bridge not available.

get_cutter_bridge()[source]

Get the Cutter/Rizin analysis bridge.

Returns:: CutterBridge instance.
Return type:: CutterBridge
Raises:: ToolError – If bridge not available.

get_x64dbg_bridge()[source]

Get the x64dbg debugger bridge.

Returns:: X64DbgBridge instance.
Return type:: X64DbgBridge
Raises:: ToolError – If bridge not available.

get_sandbox_bridge()[source]

Get the sandbox bridge.

Returns:: SandboxBridge instance.
Return type:: SandboxBridge
Raises:: ToolError – If bridge not available.

get_hex_editor_bridge()[source]

Get the hex editor bridge.

Returns:: HexEditorBridge instance.
Return type:: HexEditorBridge
Raises:: ToolError – If bridge not available.

async get_status(name)[source]

Get status of a tool.

Parameters:: name (ToolName) – Tool name.
Returns:: ToolStatus instance.
Return type:: ToolStatus

async get_all_status()[source]

Get status of all tools.

Returns:: List of ToolStatus instances.
Return type:: list[ToolStatus]

get_tool_definitions()[source]

Get tool definitions for LLM function calling.

Bridge definitions come first and externally-sourced ones follow, so a provider that truncates a long tool list at its own cap drops third-party tools before it drops an Intellicrack bridge.

Returns:: List of ToolDefinition instances.
Return type:: list[ToolDefinition]

get_available_tools()[source]

Get list of available tools.

Returns:: List of available tool names.
Return type:: list[ToolName]

async execute_tool_call(tool_name, function_name, arguments)[source]

Execute a tool function call.

Parameters:

tool_name (str) – Name of the tool (e.g., “ghidra”, “frida”).
function_name (str) – Function to call (e.g., “decompile”, “hook_function”).
arguments (dict[str, Any]) – Function arguments.

Returns:

Result of the function call.

Return type:

object

Raises:

ToolError – If execution fails.

async ensure_tool_ready(name)[source]

Ensure a tool is ready for use.

Initializes the tool if not already initialized.

Parameters:: name (ToolName) – Tool name.
Returns:: True if tool is ready.
Return type:: bool