ToolLifecycleRegistry

KIT · class · Runtime value

Registry of tools whose lifecycle, protocols and context contributions the App declares.

Registration is only possible before seal(); afterwards the catalog is read-only, so a run cannot change which tools exist. Every hook is optional and is applied in registration order, which is why registerAll preserves iteration order.

Import

TypeScript

import { ToolLifecycleRegistry } from '@jangts/agent-core/kits/tools';

JavaScript

import { ToolLifecycleRegistry } from '@jangts/agent-core/kits/tools';

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/kits/tools, @jangts/agent-core/kits.

Definition

class ToolLifecycleRegistry<Types, Declaration>

Type parameters

Type parameter	Constraint	Default type
Types	ToolRuntimeTypes	—
Declaration	ToolRegistration<Types>	ToolRegistration<Types>

Constructor

new ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types> = ToolRegistration<Types>>(options: ToolsOptions<Types, Declaration>): ToolLifecycleRegistry<Types, Declaration>

Parameter	Type	Passing	Description
options	ToolsOptions<Types, Declaration>	Required	—

Fields of options

Field	Type	Required	Description
receiver	(() => Types["receiver"]) | undefined	Optional	Read-only. Supplies the receiver handed to the finalizer.
execution	ExecutionOptions | undefined	Optional	Read-only. Execution defaults (signal and diagnostics) applied to invocations.
errors	Pick<ToolRegistryPorts, "unavailable" | "errorCode"> | undefined	Optional	Read-only. Error factories shared by the registry.
registration	Policy<Declaration>	Required	Read-only. Registration policy for every tool.
invocationId	(decision: Types["decision"]) => string	Required	Read-only. Maps a decision to the invocation id that should handle it.
outputs	() => Iterable<readonly [string, ToolProtocol<Declaration>]>	Required	Read-only. Output protocols by id, used to validate invocation outputs.
modelOutputs	((context: Types["context"]) => Iterable<readonly [string, ToolProtocol<Declaration>]>) | undefined	Optional	Read-only. Optional context-dependent output protocols, exposed alongside outputs.
unavailableInvocation	((invocationId: string) => Error) | undefined	Optional	Read-only. Builds the error for an invocation id with no registered tool.
forbidden	(() => Error) | undefined	Optional	Read-only. Builds the error for a tool that is currently unavailable.
contextFragment	(tool: Declaration, field: ToolModelField<Types["placement"]>) => ContextFragment	Required	Read-only. Renders a model field into a context fragment.
goalIds	() => readonly string[]	Required	Read-only. Current goal ids, used to validate goalIds: 'all' availability.
logger	((context: Types["context"]) => import("../debug.js").SubFlowLogger | undefined) | undefined	Optional	Read-only. Explicit recorder selected for this invocation only.
diagnostics	((context: Types["context"]) => import("../diagnostics.js").DiagnosticContext | undefined) | undefined	Optional	Read-only. Diagnostic scope; omitted disables recording for this tool.
signal	((context: Types["context"]) => AbortSignal | undefined) | undefined	Optional	Read-only. Extra cancellation; must not replace the tool execution signal.
journal	((context: Types["context"]) => ToolJournal | undefined) | undefined	Optional	Read-only. Journal receiving begin/finish receipts.
checkpoint	((context: Types["context"]) => unknown) | undefined	Optional	Read-only. Extracts the domain checkpoint recorded with the receipt.
receipt	((context: Types["context"], checkpoint: unknown) => unknown) | undefined	Optional	Read-only. Builds the domain receipt from a checkpoint after execution.
receiptError	((error: unknown) => unknown) | undefined	Optional	Read-only. Converts an error into the receipt's replacement value.

Returns: ToolLifecycleRegistry<Types, Declaration>.

Instance properties

Field	Type	Required	Description
events	readonly Readonly<ToolExecutionEvent<PreparedTool<Types, Declaration>["kind"]>>[]	Required	Read-only. Core tool events, forwarded unchanged.
definitions	readonly Readonly<Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; }>[]	Required	Read-only. Registered tools in registration order.

Member index

Member	Purpose
setDiagnostics	Swap the diagnostics sink for later invocations; the Core registry is updated as well.
register	Register and freeze one tool definition. Handlers are bound to the original object; authorization, inspection and finalization hooks must return void synchronously, while the remaining handlers are checked for accidental thenables only.
registerAll	Register every tool in iteration order.
invoke	Invoke one Core tool by its already-validated request. When the request carries no diagnostics, the currently active one is used, so a call made from inside a tool inherits that tool's diagnostic context.
ids	Registered tool ids, delegated to the Core registry.
entries	Iterate [id, tool] pairs.
get	Registered tool for id, or undefined when it is absent.
require	Registered tool for id.
has	Whether a tool id is registered.
values	Iterate the registered tools.
hasDelegate	Whether a delegate id is claimed by a registered tool.
registerNormalizer	Install the single normalization handler.
normalize	Apply the installed normalizer, or return the value unchanged when none exists.
registerFinalizer	Install the single reply finalizer.
finish	Run the installed finalizer over a decision.
call	Run the invocation that answers one decision next. Delegation is the App's choice; this method only executes the tool that claimed the id, so a purely programmatic node, a model choice and a mixed pipeline all dispatch the same way. Diagnostics are swapped to the invocation's own sink for the duration of the call and restored afterwards, so nested tool calls report under the innermost scope.
protocols	Output protocols plus one protocol per registered invocation.
modelProtocols	Protocols exposed to the model: output protocols plus invocations whose audience is model and which are currently available in context.
isTerminal	Whether the protocol registered for this invocation is declared terminal.
assertDecision	Run inspect for every registered tool in registration order. inspect belongs to the all-tools group, so the selected tool participates exactly once through the same loop rather than through a second selected-only pass.
authorize	Run the selected invocation's authorization hook, if any.
resume	Whether the selected invocation should resume rather than start fresh; defaults to false.
complete	Let the selected invocation rewrite the decision on completion, if it declares a hook.
projectContext	Fold every tool's context projection over the value, in registration order.
visibleText	Fold every tool's visible-text transform over the text.
reviewDraft	Fold every tool's review transform over the draft.
recoveryContext	Collected recovery context values; undefined results are omitted.
composition	The single output template that owns this delivery.
finalize	Run every tool's finalize hook for the given phase.
missingInteractionAllowed	Whether any tool permits the interaction to be missing.
taskRules	Task rules ordered by their declared order, joined into one prompt block.
contextFields	Model-context fragments for one placement, ordered by each field's order.
modelFields	Merged model-context values for one placement; later fragments win per key.
supportsGoal	A tool may veto a goal by returning false; silence means support.
describe	Describe registered tools, optionally limited by audience and availability. A tool with an available predicate is only listed when a context is supplied and the predicate holds, so a caller that omits the context sees just the unconditional tools.
copyTo	Reinstall every registered tool, plus the finalizer and normalizer, into another registry. The original definitions are reused rather than the compiled views, so the target applies its own policy checks and binding exactly as it would for a first registration.
seal	Freeze the registry: no further registration, normalizer or finalizer is accepted.

Member details

setDiagnostics

Instance method.

Swap the diagnostics sink for later invocations; the Core registry is updated as well.

setDiagnostics(value: ToolRegistryPorts["diagnostics"]): void

Swap the diagnostics sink for later invocations; the Core registry is updated as well.

Parameter	Type	Passing	Description
value	DiagnosticContext | undefined	Required	—

Optional shapes of Parameter value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
identity	Readonly<DiagnosticIdentity> | undefined	Optional	Read-only. Identity of the current scope, when the scope is bound to an execution.
enabled	(event: CoreEventName, content?: "metadata" | "content") => boolean	Required	Cheap pre-check so callers can skip building expensive payloads.
emit	<K extends CoreEventName>(event: K, payload: () => CoreEventPayloads[K], debug?: DebugStepsOutput) => void	Required	Records one fact.
deliver	<K extends CoreEventName>(event: K, payload: () => CoreEventPayloads[K], sink: (event: Extract<CoreEvent, { type: K; }>) => void | Promise<void>) => Promise<void>	Required	Ordered content delivery uses the same fact, while consumer failures propagate.
child	(spanId: string, fields?: Readonly<DiagnosticSpanFields>) => DiagnosticContext	Required	Derives a child span; fields fills values the child knows but the parent does not.
withObserver	(observer: import("./execution/events.js").ExecutionObserver) => DiagnosticContext	Required	Bind live observation without changing the log destination or request identity.

Returns: void.

register

Instance method.

Register and freeze one tool definition.

Handlers are bound to the original object; authorization, inspection and finalization hooks must return void synchronously, while the remaining handlers are checked for accidental thenables only.

register(input: Declaration): ToolLifecycleRegistry<Types, Declaration>

Register and freeze one tool definition.

Handlers are bound to the original object; authorization, inspection and finalization hooks must return void synchronously, while the remaining handlers are checked for accidental thenables only.

Parameter	Type	Passing	Description
input	Declaration	Required	—

Returns: ToolLifecycleRegistry<Types, Declaration>.

registerAll

Instance method.

Register every tool in iteration order.

registerAll(tools: Iterable<Declaration>): ToolLifecycleRegistry<Types, Declaration>

Register every tool in iteration order.

Parameter	Type	Passing	Description
tools	Iterable<Declaration>	Required	—

Returns: ToolLifecycleRegistry<Types, Declaration>.

invoke

Instance method.

Invoke one Core tool by its already-validated request.

When the request carries no diagnostics, the currently active one is used, so a call made from inside a tool inherits that tool's diagnostic context.

invoke(request: ToolInvocationRequest): ToolResult<unknown>

Invoke one Core tool by its already-validated request.

When the request carries no diagnostics, the currently active one is used, so a call made from inside a tool inherits that tool's diagnostic context.

Parameter	Type	Passing	Description
request	ToolInvocationRequest<string>	Required	—

Fields of request

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Explicit recorder for this call, also available to its handler for deliberate use.
toolId	string	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. Raw model arguments; parsed by the tool's input schema before authorization.
signal	AbortSignal | undefined	Optional	Read-only. Per-call cancellation; can only shorten the surrounding execution lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. See the type definition and usage context.

Returns: ToolResult<unknown>.

Return value structure

Field	Type	Required	Description
value	unknown	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ToolCallRecord>	Required	Read-only. See the type definition and usage context.

ids

Instance method.

Registered tool ids, delegated to the Core registry.

ids(): readonly string[]

Registered tool ids, delegated to the Core registry.

No call parameters.

Returns: readonly string[].

entries

Instance method.

Iterate [id, tool] pairs.

entries(): IterableIterator<[string, RegisteredToolDefinition<Types, Declaration>]>

Iterate [id, tool] pairs.

No call parameters.

Returns: IterableIterator<[string, Readonly<Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" \| "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> \| undefined; goalIds: Readonly<Declaration["goalIds"]>; }>]>.

get

Instance method.

Registered tool for id, or undefined when it is absent.

get(id: string): RegisteredToolDefinition<Types, Declaration> | undefined

Registered tool for id, or undefined when it is absent.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" \| "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> \| undefined; goalIds: Readonly<Declaration["goalIds"]>; }> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["id"]	Required	Read-only. See the type definition and usage context.
description	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["description"]	Required	Read-only. See the type definition and usage context.
resolve	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["resolve"]	Required	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.
inputSchema	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["inputSchema"]	Required	Read-only. Schema describing the arguments; must be an object schema.
active	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["active"] | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["asIntent"] | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
kind	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["kind"]	Required	Read-only. See the type definition and usage context.
execute	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["execute"]	Required	See the type definition and usage context.
debugSteps	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["debugSteps"] | undefined	Optional	Read-only. See the type definition and usage context.
parseOutput	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["parseOutput"]	Required	See the type definition and usage context.
parseInput	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["parseInput"]	Required	See the type definition and usage context.
audience	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["audience"]	Required	Read-only. Audience this tool is described to; validated against the registry policy.
effect	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["effect"]	Required	Read-only. Declared effect class, for example read-only or mutating.
delegate	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["delegate"] | undefined	Optional	Read-only. Delegate id this tool answers, when a node delegates execution by name.
lifecycle	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["lifecycle"] | undefined	Optional	See the type definition and usage context.
goalIds	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["goalIds"]	Required	See the type definition and usage context.

require

Instance method.

Registered tool for id.

require(id: string): RegisteredToolDefinition<Types, Declaration>

Registered tool for id.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" \| "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> \| undefined; goalIds: Readonly<Declaration["goalIds"]>; }>.

Return value structure

Field	Type	Required	Description
id	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["id"]	Required	Read-only. See the type definition and usage context.
description	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["description"]	Required	Read-only. See the type definition and usage context.
resolve	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["resolve"]	Required	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.
inputSchema	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["inputSchema"]	Required	Read-only. Schema describing the arguments; must be an object schema.
active	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["active"] | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["asIntent"] | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
kind	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["kind"]	Required	Read-only. See the type definition and usage context.
execute	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["execute"]	Required	See the type definition and usage context.
debugSteps	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["debugSteps"] | undefined	Optional	Read-only. See the type definition and usage context.
parseOutput	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["parseOutput"]	Required	See the type definition and usage context.
parseInput	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["parseInput"]	Required	See the type definition and usage context.
audience	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["audience"]	Required	Read-only. Audience this tool is described to; validated against the registry policy.
effect	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["effect"]	Required	Read-only. Declared effect class, for example read-only or mutating.
delegate	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["delegate"] | undefined	Optional	Read-only. Delegate id this tool answers, when a node delegates execution by name.
lifecycle	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["lifecycle"] | undefined	Optional	See the type definition and usage context.
goalIds	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> | undefined; goalIds: Readonly<Declaration["goalIds"]>; })["goalIds"]	Required	See the type definition and usage context.

has

Instance method.

Whether a tool id is registered.

has(name: string): boolean

Whether a tool id is registered.

Parameter	Type	Passing	Description
name	string	Required	—

Returns: boolean.

values

Instance method.

Iterate the registered tools.

values(): IterableIterator<RegisteredToolDefinition<Types, Declaration>>

Iterate the registered tools.

No call parameters.

Returns: IterableIterator<Readonly<Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" \| "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]> \| undefined; goalIds: Readonly<Declaration["goalIds"]>; }>>.

hasDelegate

Instance method.

Whether a delegate id is claimed by a registered tool.

hasDelegate(id: string): boolean

Whether a delegate id is claimed by a registered tool.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

registerNormalizer

Instance method.

Install the single normalization handler.

registerNormalizer(handler: ToolNormalizer<Types>): void

Install the single normalization handler.

Parameter	Type	Passing	Description
handler	ToolNormalizer<Types>	Required	—

Returns: void.

normalize

Instance method.

Apply the installed normalizer, or return the value unchanged when none exists.

normalize(value: unknown, ...args: Types["normalizerArgs"]): unknown

Apply the installed normalizer, or return the value unchanged when none exists.

Parameter	Type	Passing	Description
value	unknown	Required	—
args	Types["normalizerArgs"]	Rest parameter	—

Returns: unknown.

registerFinalizer

Instance method.

Install the single reply finalizer.

registerFinalizer(handler: ToolFinalizer<Types>): void

Install the single reply finalizer.

Parameter	Type	Passing	Description
handler	ToolFinalizer<Types>	Required	—

Returns: void.

finish

Instance method.

Run the installed finalizer over a decision.

finish(receiver: Types["receiver"], decision: Types["decision"], context: Types["context"]): Types["result"]

Run the installed finalizer over a decision.

Parameter	Type	Passing	Description
receiver	Types["receiver"]	Required	—
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—

Returns: Types["result"].

Awaited value: Awaited<Types["result"]>.

call

Instance method.

Run the invocation that answers one decision next.

Delegation is the App's choice; this method only executes the tool that claimed the id, so a purely programmatic node, a model choice and a mixed pipeline all dispatch the same way.

Diagnostics are swapped to the invocation's own sink for the duration of the call and restored afterwards, so nested tool calls report under the innermost scope.

call(next: { type: string; }, context: Types["context"]): void

Run the invocation that answers one decision next.

Delegation is the App's choice; this method only executes the tool that claimed the id, so a purely programmatic node, a model choice and a mixed pipeline all dispatch the same way.

Diagnostics are swapped to the invocation's own sink for the duration of the call and restored afterwards, so nested tool calls report under the innermost scope.

Parameter	Type	Passing	Description
next	{ type: string; }	Required	—
context	Types["context"]	Required	—

Fields of next

Field	Type	Required	Description
type	string	Required	See the type definition and usage context.

Returns: void.

protocols

Instance method.

Output protocols plus one protocol per registered invocation.

protocols(): ProtocolRegistry<ToolProtocol<Declaration>>

Output protocols plus one protocol per registered invocation.

No call parameters.

Returns: ProtocolRegistry<ToolProtocol<Declaration>>.

modelProtocols

Instance method.

Protocols exposed to the model: output protocols plus invocations whose audience is model and which are currently available in context.

modelProtocols(context: Types["context"]): ProtocolRegistry<ToolProtocol<Declaration>>

Protocols exposed to the model: output protocols plus invocations whose audience is model and which are currently available in context.

Parameter	Type	Passing	Description
context	Types["context"]	Required	—

Returns: ProtocolRegistry<ToolProtocol<Declaration>>.

isTerminal

Instance method.

Whether the protocol registered for this invocation is declared terminal.

isTerminal(next: { type: string; }): boolean

Whether the protocol registered for this invocation is declared terminal.

Parameter	Type	Passing	Description
next	{ type: string; }	Required	—

Fields of next

Field	Type	Required	Description
type	string	Required	See the type definition and usage context.

Returns: boolean.

assertDecision

Instance method.

Run inspect for every registered tool in registration order.

inspect belongs to the all-tools group, so the selected tool participates exactly once through the same loop rather than through a second selected-only pass.

assertDecision(decision: Types["decision"], context: Types["context"]): void

Run inspect for every registered tool in registration order.

inspect belongs to the all-tools group, so the selected tool participates exactly once through the same loop rather than through a second selected-only pass.

Parameter	Type	Passing	Description
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—

Returns: void.

authorize

Instance method.

Run the selected invocation's authorization hook, if any.

authorize(decision: Types["decision"], context: Types["context"]): void

Run the selected invocation's authorization hook, if any.

Parameter	Type	Passing	Description
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—

Returns: void.

resume

Instance method.

Whether the selected invocation should resume rather than start fresh; defaults to false.

resume(decision: Types["decision"], context: Types["context"]): boolean

Whether the selected invocation should resume rather than start fresh; defaults to false.

Parameter	Type	Passing	Description
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—

Returns: boolean.

complete

Instance method.

Let the selected invocation rewrite the decision on completion, if it declares a hook.

complete(decision: Types["decision"], context: Types["context"]): Types["decision"] | undefined

Let the selected invocation rewrite the decision on completion, if it declares a hook.

Parameter	Type	Passing	Description
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—

Returns: Types["decision"] \| undefined.

Awaited value: Awaited<Types["decision"]> \| undefined.

projectContext

Instance method.

Fold every tool's context projection over the value, in registration order.

projectContext(value: unknown): unknown

Fold every tool's context projection over the value, in registration order.

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

visibleText

Instance method.

Fold every tool's visible-text transform over the text.

visibleText(text: string, context: Types["context"]): string

Fold every tool's visible-text transform over the text.

Parameter	Type	Passing	Description
text	string	Required	—
context	Types["context"]	Required	—

Returns: string.

reviewDraft

Instance method.

Fold every tool's review transform over the draft.

reviewDraft(draft: unknown, context: Types["context"]): unknown

Fold every tool's review transform over the draft.

Parameter	Type	Passing	Description
draft	unknown	Required	—
context	Types["context"]	Required	—

Returns: unknown.

recoveryContext

Instance method.

Collected recovery context values; undefined results are omitted.

recoveryContext(context: Types["context"]): unknown[]

Collected recovery context values; undefined results are omitted.

Parameter	Type	Passing	Description
context	Types["context"]	Required	—

Returns: unknown[].

composition

Instance method.

The single output template that owns this delivery.

composition(context: Types["context"]): Types["composition"] | undefined

The single output template that owns this delivery.

Parameter	Type	Passing	Description
context	Types["context"]	Required	—

Returns: Types["composition"] \| undefined.

Awaited value: Awaited<Types["composition"]> \| undefined.

finalize

Instance method.

Run every tool's finalize hook for the given phase.

finalize(decision: Types["decision"], context: Types["context"], phase: Types["phase"]): void

Run every tool's finalize hook for the given phase.

Parameter	Type	Passing	Description
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—
phase	Types["phase"]	Required	—

Returns: void.

missingInteractionAllowed

Instance method.

Whether any tool permits the interaction to be missing.

missingInteractionAllowed(decision: Types["decision"], context: Types["context"]): boolean

Whether any tool permits the interaction to be missing.

Parameter	Type	Passing	Description
decision	Types["decision"]	Required	—
context	Types["context"]	Required	—

Returns: boolean.

taskRules

Instance method.

Task rules ordered by their declared order, joined into one prompt block.

taskRules(context: Types["context"]): string

Task rules ordered by their declared order, joined into one prompt block.

Parameter	Type	Passing	Description
context	Types["context"]	Required	—

Returns: string.

contextFields

Instance method.

Model-context fragments for one placement, ordered by each field's order.

contextFields(context: Types["context"], placement: Types["placement"]): ContextFragment[]

Model-context fragments for one placement, ordered by each field's order.

Parameter	Type	Passing	Description
context	Types["context"]	Required	—
placement	Types["placement"]	Required	—

Returns: ContextFragment[].

modelFields

Instance method.

Merged model-context values for one placement; later fragments win per key.

modelFields(context: Types["context"], placement: Types["placement"]): Record<string, unknown>

Merged model-context values for one placement; later fragments win per key.

Parameter	Type	Passing	Description
context	Types["context"]	Required	—
placement	Types["placement"]	Required	—

Returns: Record<string, unknown>.

supportsGoal

Instance method.

A tool may veto a goal by returning false; silence means support.

supportsGoal(intentId: string, context: Types["context"]): boolean

A tool may veto a goal by returning false; silence means support.

Parameter	Type	Passing	Description
intentId	string	Required	—
context	Types["context"]	Required	—

Returns: boolean.

describe

Instance method.

Describe registered tools, optionally limited by audience and availability.

A tool with an available predicate is only listed when a context is supplied and the predicate holds, so a caller that omits the context sees just the unconditional tools.

describe(audience?: string, context?: Types["context"]): { id: Declaration["id"]; kind: Declaration["kind"]; description: Declaration["description"]; audience: Declaration["audience"]; effect: Declaration["effect"]; goalIds: string[]; }[]

Describe registered tools, optionally limited by audience and availability.

A tool with an available predicate is only listed when a context is supplied and the predicate holds, so a caller that omits the context sees just the unconditional tools.

Parameter	Type	Passing	Description
audience	string | undefined	Optional	—
context	Types["context"] | undefined	Optional	—

Returns: { id: Declaration["id"]; kind: Declaration["kind"]; description: Declaration["description"]; audience: Declaration["audience"]; effect: Declaration["effect"]; goalIds: string[]; }[].

copyTo

Instance method.

Reinstall every registered tool, plus the finalizer and normalizer, into another registry.

The original definitions are reused rather than the compiled views, so the target applies its own policy checks and binding exactly as it would for a first registration.

copyTo(target: ToolLifecycleRegistry<Types, Declaration>): void

Reinstall every registered tool, plus the finalizer and normalizer, into another registry.

The original definitions are reused rather than the compiled views, so the target applies its own policy checks and binding exactly as it would for a first registration.

Parameter	Type	Passing	Description
target	ToolLifecycleRegistry<Types, Declaration>	Required	—

Returns: void.

seal

Instance method.

Freeze the registry: no further registration, normalizer or finalizer is accepted.

seal(): ToolLifecycleRegistry<Types, Declaration>

Freeze the registry: no further registration, normalizer or finalizer is accepted.

No call parameters.

Returns: ToolLifecycleRegistry<Types, Declaration>.

Examples

• Tools: App tool lifecycle and content contribution: Register tool invocations, output rules, context contribution, and delivery handling for existing complex App tools in one place.

Register one read-only tool for an existing App

Beginner · Node.js

TypeScript

import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
  registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
  invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
  contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));

JavaScript

import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
    registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
    invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
    contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));

Add App rules and presentation contribution to the same registration

Configuration · Node.js

active affects real tool availability and description; business authorization must still verify server-side identity at the actual invocation boundary.

TypeScript

import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
  registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
  invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
  contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
  parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
  lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
}]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));

JavaScript

import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
    registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
    invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
    contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
        parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
        lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
    }]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));

Related policy source

• Registration policy, lifecycle binding, and content projection

Related definitions

• ContextFragment
• DiagnosticContext
• ProtocolRegistry
• RegisteredToolDefinition
• ToolCallRecord
• ToolExecutionEvent
• ToolFinalizer
• ToolInvocationRequest
• ToolNormalizer
• ToolProtocol
• ToolRegistration
• ToolRegistryPorts
• ToolResult
• ToolRuntimeTypes
• ToolsOptions