Interface: ToolRegistry
Defined in: internal/tool-registry/ToolRegistry.ts:75
ToolRegistry -- the fixed catalog of the gateway's tools and the one place a tool runs
About
Every tool the gateway knows, and the only door through which one executes.
Holds the IToolDefs of the config and runs a tool on the model's behalf: input validated against the
tool's schema, the run under a timeout, the output under a size cap, so every tool, registry or per-call,
goes through the same pipeline (D60, D66).
- Fixed at construction: nothing is added or removed later (D48).
- Executes only tools the run was offered; a name outside them is refused.
- Turns a tool's failure into an error the model can read, never into a crashed run: a
dynaErrorkeeps itscode,statusanduserMessage; anything else is wrapped so the model reads a generic text, never the raw message.
Sits under ToolPolicy, which decides what the model is offered and what needs approval; the agent
loop of the LLMClient calls back into it through the run hooks to execute.
Who needs it
createRunHooks (execute), prepareCall and AIProfileStore (list, to resolve and validate tools),
splitRunTools (get, to rebuild the tools of a paused run).
What needs
IToolRegistryConfig: the tools, the default timeout and the default output cap.
Usage
When to use it
Any place that needs a tool by name or the whole catalog; executing a tool from the agent loop.
When shouldn't use it
Deciding which tools a call gets or whether a call needs approval: that is ToolPolicy.
Pitfalls
The abortSignal a tool receives is advisory: a tool that ignores it keeps running after the 504 was reported or the
call was aborted, and its late result is dropped. An abort never undoes what a tool already did.
See docs/60-architecture/90-decisions.md § ToolRegistry.
Implements
Methods
execute()
execute(
__namedParameters):Promise<unknown>
Defined in: internal/tool-registry/ToolRegistry.ts:180
execute -- runs one tool for the model, through the one pipeline
About
Validate, run under the timeout, cap the output.
- A 403 when the name is not among the offered
tools. - A 400 naming the field when the input fails the tool's schema.
- A 504 when the tool gives no answer within its timeout; its
abortSignalis aborted (D60). - A 413 when the output, as JSON text, exceeds the tool's cap (D60).
- The call's
abortSignal, when given, is merged into the tool's: once the input is validated, an aborted call aborts the tool andexecuterejects with the signal's reason at once, not with a 504 and not logged (the caller asked for it).
Every failure is reported to IToolRegistryConfig.onToolError with the whole picture (IToolErrorReport) when the call
comes with its callContext; a direct call outside a run is not reported. The abort is never reported.
Runs inside the agent loop, after ToolPolicy.decide said ALLOW (or after the human approved).
Who needs it
createRunHooks, as the loop's executeTool hook.
Pitfalls
The thrown errors are logged on the server and fed to the model as the tool's result; they never end the run. The one
exception is the call's abort: its reason is thrown as it is and ends the run (D90).
input and the result are unknown on purpose: the tool is chosen by name at runtime and the input comes from
the model; the types live on IToolDef<TInput, TOutput>.
Parameters
__namedParameters
abortSignal?
AbortSignal
The call's signal: aborted when the caller stops the call or its deadline passes.
callContext?
The call's place in its run, for the failure report; omitted for a direct call outside a run (not reported).
input
unknown
As the model sent it; validated here against the tool's schema.
name
string
threadId
string
tools?
IToolDef<unknown, unknown>[]
The tools offered to this run, the call's additional ones among them (D66).
When given, the only tools the call may run; a name outside them is a 403.
Omit only for direct use outside a run: the registry is then the catalog.
userContext
Returns
Promise<unknown>
Implementation of
IToolRegistry.execute
get()
get(
__namedParameters):IToolDef
Defined in: internal/tool-registry/ToolRegistry.ts:120
get -- one tool definition by name
About
The catalog lookup; a 404 when the name is unknown.
Who needs it
splitRunTools, to rebuild the registry tools of a paused run from their stored names.
Parameters
__namedParameters
name
string
Returns
Implementation of
IToolRegistry.get
list()
list():
IToolDef<unknown,unknown>[]
Defined in: internal/tool-registry/ToolRegistry.ts:146
list -- every tool definition, in config order
About
The whole catalog, unfiltered.
Who needs it
prepareCall, which hands it to ToolPolicy.resolve; AIProfileStore, to validate a profile's tool names.
Returns
IToolDef<unknown, unknown>[]
Implementation of
IToolRegistry.list
reportFailure()
reportFailure(
__namedParameters):void
Defined in: internal/tool-registry/ToolRegistry.ts:292
reportFailure -- hands a failed tool call to IToolRegistryConfig.onToolError
About
The developer's channel, fed from the one place that knows the whole call.
Builds the IToolErrorReport (the text the model reads included, formatToolError) and delivers it without waiting:
the run never waits for the handler, and a handler that throws or rejects is logged (5376189327034) and ignored.
Nothing happens without a handler.
Who needs it
execute, for every failure it throws; createRunHooks, for the refusal ToolPolicy.assertOfferedInStep throws
before the registry is reached (D88) — the same report for the model's every failed call.
Parameters
__namedParameters
callContext
error
unknown
As thrown.
input
unknown
Parsed when the schema accepted it, raw otherwise.
name
string
startedAt
number
Date.now() when the call started; the report's durationMs is measured from it.
threadId
string
userContext
Returns
void
Implementation of
IToolRegistry.reportFailure