RegisteredToolDefinition

KIT · type · Type contract

Registered snapshot with frozen goal ids and projected hooks.

Import

TypeScript

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

JavaScript

/** @typedef {import('@jangts/agent-core/kits/tools').RegisteredToolDefinition} RegisteredToolDefinition */

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

Definition

Type: RegisteredToolDefinition<Types, Declaration>

Type expression

type RegisteredToolDefinition<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types> = ToolRegistration<Types>> = Readonly<
  Omit<RegistrationProjection<Declaration, Tool<Types>>, 'lifecycle' | 'goalIds'> & {
    lifecycle?: RegisteredLifecycle<Types, Declaration['lifecycle']>;
    goalIds: Readonly<Declaration['goalIds']>;
  }
>;

Type parameters

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

Field 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; 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"]>; goalIds: Readonly<Declaration["goalIds"]>; })["goalIds"]	Required	See the type definition and usage context.

Member index

Member	Purpose
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.
execute	See the overload below for full inputs and outputs.
parseOutput	See the overload below for full inputs and outputs.
parseInput	See the overload below for full inputs and outputs.

Member details

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.

RegisteredToolDefinition.resolve(input: unknown, context: Readonly<{ stageId: string; }>): unknown

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.

Parameter	Type	Passing	Description
input	unknown	Required	—
context	Readonly<{ stageId: string; }>	Required	—

Fields of context

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

Returns: unknown.

execute

RegisteredToolDefinition.execute(input: unknown, context: ToolExecutionContext): unknown

Parameter	Type	Passing	Description
input	unknown	Required	—
context	ToolExecutionContext	Required	—

Fields of context

Field	Type	Required	Description
logger	ScopedSubFlowLogger | undefined	Optional	Read-only. Delegate bound by Core to this actual invocation.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the invocation, when recording is enabled.
mode	"sync" | "async"	Required	Read-only. Declared execution discipline; mirrors whether the registry accepted an async tool.
invocationId	string	Required	Read-only. Opaque invocation id shared by receipt, events and diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation for this invocation.
report	(update: import("./execution/workflow.js").WorkflowNodeReport) => void	Required	Reports progress for the active node; Core supplies the execution identity.
createSubFlowLogger	() => SubFlowLogger	Required	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

Returns: unknown.

parseOutput

RegisteredToolDefinition.parseOutput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

parseInput

RegisteredToolDefinition.parseInput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

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

• Tool
• ToolExecutionContext
• ToolRegistration
• ToolRuntimeTypes