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

LayerOwnsDoes not own
ToolOperation behavior, validation, typed resultConsole rendering, HTTP response shape, UI state
CLIArgument parsing and terminal outputBusiness logic
AI agentTool selection through the model runtimeSeparate tool implementations
HTTP APIRequest/response transportOperation-specific logic
Tool RegistryHTTP dispatch, policy hooks, discoverabilityPer-caller UI behavior

​
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

ConcernDesign answer
Single source of truthOperation behavior lives in one tool definition.
Less schema driftTool metadata feeds CLI, agent, and HTTP surfaces.
Uniform policy enforcementRegistry dispatch is the policy boundary for HTTP callers.
DiscoverabilityThe server can expose registered tools dynamically.
Offline CLICLI commands can run without a live server.
In-process agentAgent calls avoid an unnecessary HTTP boundary.
Incremental growthNew operations follow one repeatable registration path.