Skip to main content
Every operation in Hiro League is defined once as a Tool. The CLI, the AI agent, and the HTTP API are thin callers that invoke the same operation. There is no separate CLI version, agent version, and API version of a feature. For implementation steps and code examples, see Tool implementation guide.

​
Why this design exists

Without a shared tool layer, one operation can turn into three separate implementations:
  • A CLI command for terminal users
  • An agent tool for LLM-driven actions
  • An HTTP endpoint for the web UI and external clients
Those copies drift over time. A bug fix in one caller does not automatically reach the others. Policy checks, audit logging, and parameter schemas also become inconsistent. The tool architecture makes the operation itself the single source of truth. Callers own transport, rendering, and user experience. Tools own behavior.

​
Architecture overview

The Tool is the unit of functionality. CLI commands and the AI agent can call tools in process. HTTP callers go through the Tool Registry, which gives the server one dispatch point for browser and API requests.

​
Responsibilities

​
Tool Registry boundary

The Tool Registry is the server-side entry point for callers that cannot import the Python tools directly. It keeps one registered instance of each tool and dispatches requests by name. This matters because it gives Hiro League a single place to add cross-cutting behavior for HTTP and future remote callers:
  • Source-based restrictions
  • Role-based access
  • Destructive operation confirmation
  • Rate limiting
  • Audit logging
The tools themselves do not handle caller identity or transport policy. The caller provides context, and the registry decides whether dispatch is allowed.

​
Caller model

CLI commands run outside the server process. They import tools directly, call them, and render terminal output. This keeps lifecycle operations available even when the server is stopped. AI agent tools run inside the server process. The agent receives tool schemas derived from the same tool definitions and invokes the selected tool in process. HTTP API callers use registry endpoints. The web UI discovers available tools and invokes them through the server, without hardcoding operation-specific routes.

​
Benefits summary