tools_main

Tools service entry point — dedicated, isolatable tool-execution worker.

Runs ToolsService, a StargazerService whose sole job is to execute tools on behalf of the inference tier. It is the only process that imports the tool handler modules in tools/: on boot it loads the full ToolRegistry, publishes the tool catalog to Redis (so inference can present tools without importing them), and consumes tool-execution requests off sg:stream:tools (group sg:tools, load-balanced across instances). Each request reconstructs a ToolContext from the request’s identity fields plus this service’s shared managers and a ProxyPlatformAdapter (so tool sends still publish to the gateway and raw-SDK ops still delegate to it), runs the tool, and replies on the originating worker’s reply stream with the result plus the write-back channels (sent_files media bytes, injected_tools, sent_rich_messages).

Deliberately lighter than inference: no message processor, no swarm/subagent system, no presence manager, no inbound consumer. Compound tools that spawn nested LLM loops stay pinned to inference (INFERENCE_PINNED_TOOLS); the OpenRouterClient wired here exists only for the embedding/KG managers some delegated tools use. Launched standalone (python tools_main.py) by scripts/systemd/stargazer-tools.service.

class tools_main.ToolsService(config, redis_client, instance_id, use_health_server=True)

Bases: StargazerService

Dedicated tool-execution service (service tier "tools").

Parameters:

• config (Config)

• redis_client (Any)

• instance_id (str)

• use_health_server (bool)

get_adapter(platform_name)

Return a proxy adapter so tool sends publish to the gateway’s stream.

Return type:

ProxyPlatformAdapter

Parameters:

platform_name (str)

async on_start()

Subclass hook for tier-specific startup, run during boot.

Abstract extension point invoked by boot() (its phase 3-7) after the Redis ping succeeds but before registry registration and the health server start, so each tier can stand up its own machinery – loading tools, building platform adapters, wiring stream consumers, initializing observability – on a verified Redis connection. Has no behavior here; it must be overridden.

Called by boot(); the concrete implementations live in the *_main.py service classes (InferenceService.on_start, GatewayService.on_start, etc.) and are exercised directly by the tests/core/migration suite.

Return type:

None

async run()

Subclass hook for the main service loop, run after boot.

Abstract extension point that holds the service’s long-lived work – typically consuming a Redis stream or serving HTTP – and is expected to block until shutdown is signalled. Each tier’s main awaits this immediately after boot() returns, so it defines what the process actually does for its lifetime. Has no behavior here; it must be overridden.

Called by each microservice’s main via await service.run() (in inference_main.py, gateway_main.py, web_main.py, consolidation_main.py, agents_main.py), right after service.boot().

Return type:

None

async on_stop()

Subclass hook for tier-specific cleanup, run during shutdown.

Abstract extension point invoked by shutdown() after the health server is stopped and the instance is deregistered, giving each tier a place to release what on_start() and run() stood up (platform adapters, schedulers, consumers, sockets). Has no behavior here; it must be overridden.

Called by shutdown(); concrete implementations live in the *_main.py service classes (e.g. WebService.on_stop drives a graceful uvicorn exit, GatewayService.on_stop stops platform adapters) and are covered by tests/core/migration.

Return type:

None

async tools_main.main()

Return type:

None