Policy

KIT · interface · Type contract

Registration policy shared by every tool in the registry.

Import

TypeScript

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

JavaScript

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

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 Policy<Tool>

Type parameters

Type parameter	Constraint	Default type
Tool	—	—

Field structure

Field	Type	Required	Description
kinds	readonly string[]	Required	Read-only. Accepted values of a tool's kind.
isValidId	(tool: Tool) => boolean	Required	Read-only. Identity and shape predicate; must be synchronous boolean.
audiences	readonly string[]	Required	Read-only. Accepted audience values.
effects	readonly string[]	Required	Read-only. Accepted effect values.
goalExists	(goal: string) => boolean	Required	Read-only. Reports whether a goal id exists, for validating goalIds references.
protocolVersion	number | undefined	Optional	Read-only. When set, every lifecycle protocol must declare this version.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to registration rejections.
invalidTool	BreakReason | undefined	Optional	Read-only. Rejection wording for an invalid tool definition.
invalidInvocation	BreakReason | undefined	Optional	Read-only. Rejection wording for an invalid or duplicate invocation id.

Member index

Member	Purpose
isValidId	Identity and shape predicate; must be synchronous boolean.
goalExists	Reports whether a goal id exists, for validating goalIds references.

Member details

isValidId

Identity and shape predicate; must be synchronous boolean.

Policy.isValidId(tool: Tool): boolean

Parameter	Type	Passing	Description
tool	Tool	Required	—

Returns: boolean.

goalExists

Reports whether a goal id exists, for validating goalIds references.

Policy.goalExists(goal: string): boolean

Parameter	Type	Passing	Description
goal	string	Required	—

Returns: boolean.

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

• BreakReason