ToolRegistry
Enhanced Tool Registry with security, validation, and observability. Pipeline: resolve → validate → authorize → execute → audit Features: - Token estimation for LLM context management - Tool filtering by category and scopes - Budget-aware tool selection
ToolRegistry::__construct()
public function __construct(Psr\Log\LoggerInterface $logger, ?Milpa\Interfaces\Event\MilpaEventDispatcherInterface $dispatcher = null):Parameters
| Name | Type | Description |
|---|---|---|
| $logger | LoggerInterface | PSR-3 logger for internal debug/warning output |
| $dispatcher | (MilpaEventDispatcherInterface | null) | Optional event dispatcher (tool-runtime 0.5, event-driven retrofit — {@see \Milpa\ToolRuntime\Verification\HumanVerifier} pattern). `null` (the default) preserves today's behavior EXACTLY: no `tool.executing` interception point exists, so nothing can ever short-circuit or veto a call, and audit logging (via {@see ToolAuditLogger}) still fires on every path — {@see call()} invokes the audit listener methods directly when no dispatcher is wired, so "no dispatcher" never means "no audit * trail". When a dispatcher IS supplied, this constructor subscribes the internal {@see ToolAuditLogger} to `tool.executed` / `tool.failed` exactly like any other plugin listener would — see the README's cache-plugin recipe for how a third party hooks the same `tool.executing` seam. |
ToolRegistry::register()
public function register(string $name, string $description, array $inputSchema, callable $callback, ?Milpa\ValueObjects\Tooling\ToolOptions $options = null): voidRegister a tool.
Parameters
| Name | Type | Description |
|---|---|---|
| $name | string | |
| $description | string | |
| $inputSchema | array | |
| $callback | callable | |
| $options | ?Milpa\ValueObjects\Tooling\ToolOptions |
Throws
ToolAlreadyRegisteredException if tool name already exists
ToolRegistry::getToolSummaries()
public function getToolSummaries(): arrayGet all tools as plain-array summaries, for LLM/MCP exposure. This is the wire shape: a JSON-serializable summary per tool (no callback, no internal state) — exactly what an MCP `tools/list` response or a token-budget report needs. It is NOT the internal {@see ToolDefinition} object; use {@see getToolDefinitions()} when you need the typed VO (e.g. its `->callback` or `->mutating`). Renamed from `getTools()` in tool-runtime 0.2 — the old name was easy to confuse with a `list<ToolDefinition>` getter (which `ToolDefinition` existing internally invited), and a caller assuming `->name` on these entries got a silent `null` instead of a type error.
ToolRegistry::getToolDefinitions()
public function getToolDefinitions(): arrayGet all registered tools as their typed {@see ToolDefinition} value objects. Unlike {@see getToolSummaries()}, this exposes the full internal VO — including `->callback` and `->mutating` — for consumers that need more than the LLM/MCP wire shape (e.g. building an alternate registry, introspecting tool metadata). Registration order is preserved.
ToolRegistry::getToolsByScopes()
public function getToolsByScopes(array $scopes): arrayGet tools filtered by scopes.
Parameters
| Name | Type | Description |
|---|---|---|
| $scopes | array<string> | Required scopes |
ToolRegistry::getToolsByPrefix()
public function getToolsByPrefix(string $prefix): arrayGet tools filtered by name prefix (category).
Parameters
| Name | Type | Description |
|---|---|---|
| $prefix | string | Tool name prefix (e.g., "list_", "admin_") |
ToolRegistry::getToolsWithinBudget()
public function getToolsWithinBudget(string $model, ?array $priorityTools = null): arrayGet tools that fit within token budget for a model.
Parameters
| Name | Type | Description |
|---|---|---|
| $model | string | Model identifier (e.g., "gpt-4", "claude-3-sonnet") |
| $priorityTools | (array<string> | null) | Tools to include first (by name) |
ToolRegistry::getTokenUsageReport()
public function getTokenUsageReport(string $model = 'gpt-4'): stringGet token usage report for current tools.
Parameters
| Name | Type | Description |
|---|---|---|
| $model | string |
ToolRegistry::estimateTokens()
public function estimateTokens(): arrayEstimate tokens for current tools.
ToolRegistry::checkTokenBudget()
public function checkTokenBudget(string $model): arrayCheck if tools fit within budget for a model.
Parameters
| Name | Type | Description |
|---|---|---|
| $model | string |
ToolRegistry::getTokenEstimator()
public function getTokenEstimator(): Milpa\ToolRuntime\TokenEstimatorGet the token estimator for direct use.
ToolRegistry::call()
public function call(string $name, array $args, ?Milpa\ToolRuntime\Contracts\ToolContext $ctx = null): Milpa\ToolRuntime\ToolResultCall a tool with full pipeline.
Parameters
| Name | Type | Description |
|---|---|---|
| $name | string | Tool name |
| $args | array<string, mixed> | Arguments |
| $ctx | (ToolContext | null) | Execution context (defaults to CLI) |
ToolRegistry::has()
public function has(string $name): boolCheck if a tool exists.
Parameters
| Name | Type | Description |
|---|---|---|
| $name | string |
ToolRegistry::getDefinition()
public function getDefinition(string $name): ?Milpa\ToolRuntime\ToolDefinitionGet tool definition.
Parameters
| Name | Type | Description |
|---|---|---|
| $name | string |
ToolRegistry::hasRateLimiter()
public function hasRateLimiter(): bool¿Hay un rate limiter conectado? Lectura pura para la inspección (ADR#13): permite marcar el paso rate_limit como Skipped (no wired) en vez de Conditional cuando no hay limiter.
ToolRegistry::hasDispatcher()
public function hasDispatcher(): bool¿Hay un event dispatcher conectado? Lectura pura para la inspección (ADR#13): el anchor tool.executing y sus ramas cache/veto son Skipped cuando no hay dispatcher.
ToolRegistry::getPolicyGate()
public function getPolicyGate(): Milpa\ToolRuntime\PolicyGateGet policy gate for customization.
ToolRegistry::getConfirmationStore()
public function getConfirmationStore(): Milpa\ToolRuntime\ConfirmationTokenStoreGet confirmation store for customization.
ToolRegistry::setRateLimiter()
public function setRateLimiter(Milpa\ToolRuntime\RateLimiting\RateLimiterInterface $limiter): voidSet the rate limiter for tool call throttling.
Parameters
| Name | Type | Description |
|---|---|---|
| $limiter | Milpa\ToolRuntime\RateLimiting\RateLimiterInterface |
ToolRegistry::getRateLimiter()
public function getRateLimiter(): ?Milpa\ToolRuntime\RateLimiting\RateLimiterInterfaceGet the rate limiter if configured.