ToolLifecycleRegistry

KIT · class · 运行时值

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.

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core、@jangts/agent-core/types、@jangts/agent-core/kits/tools、@jangts/agent-core/kits。

定义

class ToolLifecycleRegistry<Types, Declaration>

泛型参数

类型参数	约束	默认类型
Types	ToolRuntimeTypes	—
Declaration	ToolRegistration<Types>	ToolRegistration<Types>

构造函数

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

参数	类型	传递	说明
options	ToolsOptions<Types, Declaration>	必需	—

options 的字段

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

返回： ToolLifecycleRegistry<Types, Declaration>。

实例属性

字段	类型	必需	说明
events	readonly Readonly<ToolExecutionEvent<PreparedTool<Types, Declaration>["kind"]>>[]	必需	只读。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"]>; }>[]	必需	只读。Registered tools in registration order.

成员目录

成员	用途
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.

成员详情

setDiagnostics

实例方法。

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.

参数	类型	传递	说明
value	DiagnosticContext | undefined	必需	—

参数 value的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

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

返回： void。

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.

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.

参数	类型	传递	说明
input	Declaration	必需	—

返回： ToolLifecycleRegistry<Types, Declaration>。

registerAll

实例方法。

Register every tool in iteration order.

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

Register every tool in iteration order.

参数	类型	传递	说明
tools	Iterable<Declaration>	必需	—

返回： ToolLifecycleRegistry<Types, Declaration>。

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.

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.

参数	类型	传递	说明
request	ToolInvocationRequest<string>	必需	—

request 的字段

字段	类型	必需	说明
logger	SubFlowLogger | undefined	可省略	只读。Explicit recorder for this call, also available to its handler for deliberate use.
toolId	string	必需	只读。见类型定义及调用场景。
input	unknown	必需	只读。Raw model arguments; parsed by the tool's input schema before authorization.
signal	AbortSignal | undefined	可省略	只读。Per-call cancellation; can only shorten the surrounding execution lifetime.
diagnostics	DiagnosticContext | undefined	可省略	只读。见类型定义及调用场景。

返回： ToolResult<unknown>。

返回值结构

字段	类型	必需	说明
value	unknown	必需	只读。见类型定义及调用场景。
invocation	Readonly<ToolCallRecord>	必需	只读。见类型定义及调用场景。

ids

实例方法。

Registered tool ids, delegated to the Core registry.

ids(): readonly string[]

Registered tool ids, delegated to the Core registry.

无调用参数。

返回： readonly string[]。

entries

实例方法。

Iterate [id, tool] pairs.

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

Iterate [id, tool] pairs.

无调用参数。

返回： 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

实例方法。

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.

参数	类型	传递	说明
id	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"]>; }> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
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"]	必需	只读。见类型定义及调用场景。
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"]	必需	只读。见类型定义及调用场景。
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"]	必需	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"]	必需	只读。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	可省略	只读。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	可省略	只读。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"]	必需	只读。见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。
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	可省略	只读。见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。
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"]	必需	只读。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"]	必需	只读。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	可省略	只读。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	可省略	见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。

require

实例方法。

Registered tool for id.

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

Registered tool for id.

参数	类型	传递	说明
id	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"]>; }>。

返回值结构

字段	类型	必需	说明
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"]	必需	只读。见类型定义及调用场景。
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"]	必需	只读。见类型定义及调用场景。
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"]	必需	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"]	必需	只读。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	可省略	只读。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	可省略	只读。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"]	必需	只读。见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。
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	可省略	只读。见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。
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"]	必需	只读。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"]	必需	只读。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	可省略	只读。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	可省略	见类型定义及调用场景。
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"]	必需	见类型定义及调用场景。

has

实例方法。

Whether a tool id is registered.

has(name: string): boolean

Whether a tool id is registered.

参数	类型	传递	说明
name	string	必需	—

返回： boolean。

values

实例方法。

Iterate the registered tools.

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

Iterate the registered tools.

无调用参数。

返回： 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

实例方法。

Whether a delegate id is claimed by a registered tool.

hasDelegate(id: string): boolean

Whether a delegate id is claimed by a registered tool.

参数	类型	传递	说明
id	string	必需	—

返回： boolean。

registerNormalizer

实例方法。

Install the single normalization handler.

registerNormalizer(handler: ToolNormalizer<Types>): void

Install the single normalization handler.

参数	类型	传递	说明
handler	ToolNormalizer<Types>	必需	—

返回： void。

normalize

实例方法。

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.

参数	类型	传递	说明
value	unknown	必需	—
args	Types["normalizerArgs"]	剩余参数	—

返回： unknown。

registerFinalizer

实例方法。

Install the single reply finalizer.

registerFinalizer(handler: ToolFinalizer<Types>): void

Install the single reply finalizer.

参数	类型	传递	说明
handler	ToolFinalizer<Types>	必需	—

返回： void。

finish

实例方法。

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.

参数	类型	传递	说明
receiver	Types["receiver"]	必需	—
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—

返回： Types["result"]。

等待后的值： Awaited<Types["result"]>。

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.

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.

参数	类型	传递	说明
next	{ type: string; }	必需	—
context	Types["context"]	必需	—

next 的字段

字段	类型	必需	说明
type	string	必需	见类型定义及调用场景。

返回： void。

protocols

实例方法。

Output protocols plus one protocol per registered invocation.

protocols(): ProtocolRegistry<ToolProtocol<Declaration>>

Output protocols plus one protocol per registered invocation.

无调用参数。

返回： ProtocolRegistry<ToolProtocol<Declaration>>。

modelProtocols

实例方法。

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.

参数	类型	传递	说明
context	Types["context"]	必需	—

返回： ProtocolRegistry<ToolProtocol<Declaration>>。

isTerminal

实例方法。

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.

参数	类型	传递	说明
next	{ type: string; }	必需	—

next 的字段

字段	类型	必需	说明
type	string	必需	见类型定义及调用场景。

返回： boolean。

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.

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.

参数	类型	传递	说明
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—

返回： void。

authorize

实例方法。

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.

参数	类型	传递	说明
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—

返回： void。

resume

实例方法。

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.

参数	类型	传递	说明
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—

返回： boolean。

complete

实例方法。

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.

参数	类型	传递	说明
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—

返回： Types["decision"] \| undefined。

等待后的值： Awaited<Types["decision"]> \| undefined。

projectContext

实例方法。

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.

参数	类型	传递	说明
value	unknown	必需	—

返回： unknown。

visibleText

实例方法。

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.

参数	类型	传递	说明
text	string	必需	—
context	Types["context"]	必需	—

返回： string。

reviewDraft

实例方法。

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.

参数	类型	传递	说明
draft	unknown	必需	—
context	Types["context"]	必需	—

返回： unknown。

recoveryContext

实例方法。

Collected recovery context values; undefined results are omitted.

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

Collected recovery context values; undefined results are omitted.

参数	类型	传递	说明
context	Types["context"]	必需	—

返回： unknown[]。

composition

实例方法。

The single output template that owns this delivery.

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

The single output template that owns this delivery.

参数	类型	传递	说明
context	Types["context"]	必需	—

返回： Types["composition"] \| undefined。

等待后的值： Awaited<Types["composition"]> \| undefined。

finalize

实例方法。

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.

参数	类型	传递	说明
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—
phase	Types["phase"]	必需	—

返回： void。

missingInteractionAllowed

实例方法。

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.

参数	类型	传递	说明
decision	Types["decision"]	必需	—
context	Types["context"]	必需	—

返回： boolean。

taskRules

实例方法。

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.

参数	类型	传递	说明
context	Types["context"]	必需	—

返回： string。

contextFields

实例方法。

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.

参数	类型	传递	说明
context	Types["context"]	必需	—
placement	Types["placement"]	必需	—

返回： ContextFragment[]。

modelFields

实例方法。

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.

参数	类型	传递	说明
context	Types["context"]	必需	—
placement	Types["placement"]	必需	—

返回： Record<string, unknown>。

supportsGoal

实例方法。

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.

参数	类型	传递	说明
intentId	string	必需	—
context	Types["context"]	必需	—

返回： boolean。

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.

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.

参数	类型	传递	说明
audience	string | undefined	可省略	—
context	Types["context"] | undefined	可省略	—

返回： { id: Declaration["id"]; kind: Declaration["kind"]; description: Declaration["description"]; audience: Declaration["audience"]; effect: Declaration["effect"]; goalIds: string[]; }[]。

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.

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.

参数	类型	传递	说明
target	ToolLifecycleRegistry<Types, Declaration>	必需	—

返回： void。

seal

实例方法。

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.

无调用参数。

返回： ToolLifecycleRegistry<Types, Declaration>。

使用示例

• Tools：App 工具生命周期与内容贡献：对已有复杂 App 工具统一登记工具调用、输出规则、上下文贡献和交付处理。

为已有 App 登记一个只读工具

入门 · 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 }));

同一注册方式增加 App 规则和展示贡献

配置 · Node.js

active 影响真实工具可用性及描述；业务授权仍必须在实际调用边界核对服务端身份。

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 }));

相关策略源码

• 注册策略、生命周期绑定和内容投影

相关定义

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