Interface: IToolRegistry
Defined in: internal/tool-registry/types.ts:57
Every tool the gateway knows, and the only door through which one executes.
Implemented by ToolRegistry; the type of IAIGatewayDeps.toolRegistry, so a host may pass its own in overrides.
Methods
execute()
execute(
args):Promise<unknown>
Defined in: internal/tool-registry/types.ts:114
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
args
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>
get()
get(
args):IToolDef
Defined in: internal/tool-registry/types.ts:69
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
args
name
string
Returns
list()
list():
IToolDef<unknown,unknown>[]
Defined in: internal/tool-registry/types.ts:82
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>[]
reportFailure()
reportFailure(
args):void
Defined in: internal/tool-registry/types.ts:150
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
args
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