ToolsOptions

KIT · interface · Type contract

Construction options for a tool registry.

Import

TypeScript

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

JavaScript

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

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

interface ToolsOptions<Types, Declaration>

Extends or implements: ToolInvocationPorts<Types['context']>.

Type parameters

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

Field structure

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.

Member index

Member	Purpose
invocationId	Maps a decision to the invocation id that should handle it.
outputs	Output protocols by id, used to validate invocation outputs.
contextFragment	Renders a model field into a context fragment.
goalIds	Current goal ids, used to validate goalIds: 'all' availability.

Member details

invocationId

Maps a decision to the invocation id that should handle it.

ToolsOptions.invocationId(decision: Types["decision"]): string

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

Returns: string.

outputs

Output protocols by id, used to validate invocation outputs.

ToolsOptions.outputs(): Iterable<readonly [string, ToolProtocol<Declaration>]>

No call parameters.

Returns: Iterable<readonly [string, ToolProtocol<Declaration>]>.

contextFragment

Renders a model field into a context fragment.

ToolsOptions.contextFragment(tool: Declaration, field: ToolModelField<Types["placement"]>): ContextFragment

Parameter	Type	Passing	Description
tool	Declaration	Required	—
field	ToolModelField<Types["placement"]>	Required	—

Fields of field

Field	Type	Required	Description
lifetime	ContextLifetime | undefined	Optional	Validity window of the produced fragment.
maxChars	number | undefined	Optional	Character budget of the produced fragment.
placement	Types["placement"]	Required	Placement group this field belongs to; only that placement consumes it.
order	number	Required	Ordering key; lower values are emitted first within a placement.
key	string	Required	Key inside the merged model field record; later entries win.
value	unknown	Required	Field value, rendered by the registry's fragment factory.

Returns: ContextFragment.

Return value structure

Field	Type	Required	Description
id	string	Required	Unique, stable id matching ^[a-z][a-zA-Z0-9:._-]*$; duplicates are rejected.
sourceId	string	Required	Owning source (module or registration) used to explain where the content came from.
trust	ContextTrust	Required	Producer trust level. user and tool content cannot become a system message.
lifetime	ContextLifetime	Required	Declared validity window of this content.
maxChars	number	Required	Hard upper bound in JSON characters; must be a positive safe integer.
role	"system" | "user"	Required	Message slot the fragment occupies when assembled.
value	string | Record<string, unknown>	Required	Rendered content. A system message accepts a string only, never a record.

goalIds

Current goal ids, used to validate goalIds: 'all' availability.

ToolsOptions.goalIds(): readonly string[]

No call parameters.

Returns: readonly string[].

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
• ExecutionOptions
• Policy
• ToolInvocationPorts
• ToolModelField
• ToolProtocol
• ToolRegistration
• ToolRegistryPorts
• ToolRuntimeTypes