CommandCatalog

KIT · class · Runtime value

Mode and cross-protocol field ownership checks are shared by all receiving hosts.

The catalog seals itself as soon as construction finishes, so a run cannot register a new command later; set remains available only for the superclass installation pass.

Import

TypeScript

import { CommandCatalog } from '@jangts/agent-core/kits/interaction';

JavaScript

import { CommandCatalog } from '@jangts/agent-core/kits/interaction';

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

Definition

class CommandCatalog<Value, Result, Args, Id>

Extends or implements: ProtocolRegistry<Command<Value, Result, Args> & { readonly id: Id }>.

Type parameters

Type parameter	Constraint	Default type
Value	object	Record<string, unknown>
Result	—	Value
Args	unknown[]	[]
Id	string	string

Constructor

new CommandCatalog<Value extends object = Record<string, unknown>, Result = Value, Args extends unknown[] = [], Id extends string = string>(definitions: Iterable<readonly [Id, Command<Value, Result, Args>]>, options?: CommandCatalogOptions): CommandCatalog<Value, Result, Args, Id>

Parameter	Type	Passing	Description
definitions	Iterable<readonly [Id, Command<Value, Result, Args>]>	Required	—
options	CommandCatalogOptions	Optional	—

Fields of options

Field	Type	Required	Description
modeField	string | undefined	Optional	Read-only. Field carrying the mode selector, when modes are used.
unknownError	string | Error | undefined	Optional	Read-only. Rejection wording for an unknown command selector.
modeError	string | Error | undefined	Optional	Read-only. Rejection wording for a command used outside its declared modes.
ownershipError	string | Error | undefined	Optional	Read-only. Rejection wording for a model-supplied owned field.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to every rejection from this catalog.

Returns: CommandCatalog<Value, Result, Args, Id>.

Instance properties

Field	Type	Required	Description
definitions	readonly Readonly<Command<Value, Result, Args> & { id: Id; }>[]	Required	Read-only. Compiled commands in registration order.

Member index

Member	Purpose
define	Static. Compile and construct a catalog from definitions in one call.
compile	Static. Compile a set of definitions with shared envelope fields.
set	Install one compiled command during construction.
delete	Removal is not supported.
clear	Clearing is not supported.
toRecord	Explicit dictionary projection; definitions always remains an ordered array.
manifest	The same declarations drive purpose-specific menus, documentation and handler binding.
parse	Validate and parse one payload as the named command. Checks run before the command's own parser: the id must exist, the mode (when configured) must be allowed, and no other command may claim a field that this payload sets. The last rule prevents one command from silently consuming another command's data.
ids	See the overload below for full inputs and outputs.
require	Look up a protocol that must exist.

Member details

define

Static member.

Compile and construct a catalog from definitions in one call.

CommandCatalog.define<Value extends object, Result = Value, Args extends unknown[] = [], Id extends string = string>(definitions: Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>, defaults?: Partial<CommandDefinition<Value, Result, Args>>, options?: CommandCatalogOptions): CommandCatalog<Value, Result, Args, Id>

Compile definitions and wrap them in a sealed catalog.

Type parameter	Constraint	Default type
Value	object	—
Result	—	Value
Args	unknown[]	[]
Id	string	string

Parameter	Type	Passing	Description
definitions	Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>	Required	—
defaults	Partial<CommandDefinition<Value, Result, Args>>	Optional	—
options	CommandCatalogOptions	Optional	—

Fields of defaults

Field	Type	Required	Description
category	InteractionCategory | undefined	Optional	Read-only. Declared purpose; validated against the frozen category list.
version	number | undefined	Optional	Read-only. Protocol version, used to reject incompatible registrations.
description	string | undefined	Optional	Read-only. See the type definition and usage context.
terminal	boolean | undefined	Optional	Read-only. Marks a command that ends the interaction.
discriminator	{ readonly field: string; readonly value: string; } | undefined	Optional	Read-only. Constant field identifying the command; its value is forced to the command id.
fields	readonly string[] | Readonly<Record<string, ProtocolField>> | undefined	Optional	Read-only. Field declarations by name, or an ordered list of field names.
ownedFields	readonly string[] | undefined	Optional	Read-only. Fields the program writes; may name fields not declared in fields.
additionalProperties	boolean | undefined	Optional	Read-only. Whether fields outside the declaration are rejected; defaults to the compiler policy.
optionalPresence	"own" | "defined" | undefined	Optional	Read-only. 'defined' rejects an explicitly undefined optional property; 'own' preserves its presence.
modes	readonly string[] | undefined	Optional	Read-only. App-declared modes in which the command is available.
error	ProtocolReason<Value, Args> | undefined	Optional	Read-only. Rejection wording for the command as a whole.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to rejections from this command.
checks	readonly ProtocolCheck<Value, Args>[] | undefined	Optional	Read-only. Declarative rejection rules, evaluated in order after the structural checks.
refine	((value: Value, ...args: Args) => void) | undefined	Optional	Read-only. Domain checks/bindings only; invoked after structural and declarative checks.
format	((value: Value, ...args: Args) => Result) | undefined	Optional	Read-only. Formats the validated value into the command result.

Fields of options

Field	Type	Required	Description
modeField	string | undefined	Optional	Read-only. Field carrying the mode selector, when modes are used.
unknownError	string | Error | undefined	Optional	Read-only. Rejection wording for an unknown command selector.
modeError	string | Error | undefined	Optional	Read-only. Rejection wording for a command used outside its declared modes.
ownershipError	string | Error | undefined	Optional	Read-only. Rejection wording for a model-supplied owned field.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to every rejection from this catalog.

Returns: CommandCatalog<Value, Result, Args, Id>.

compile

Static member.

Compile a set of definitions with shared envelope fields.

CommandCatalog.compile<Value extends object, Result = Value, Args extends unknown[] = [], Id extends string = string>(definitions: Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>, defaults?: Partial<CommandDefinition<Value, Result, Args>>): Readonly<Record<Id, Command<Value, Result, Args>>>

Compile a whole catalog with shared envelope fields.

Applications declare only their own data and handlers. Defaults are merged in this order: unrelated default keys, then the command's own keys, with fields, checks and tags concatenated so shared envelope checks always run before per-command checks.

Type parameter	Constraint	Default type
Value	object	—
Result	—	Value
Args	unknown[]	[]
Id	string	string

Parameter	Type	Passing	Description
definitions	Readonly<Record<Id, CommandDefinition<Value, Result, Args>>>	Required	—
defaults	Partial<CommandDefinition<Value, Result, Args>>	Optional	—

Fields of defaults

Field	Type	Required	Description
category	InteractionCategory | undefined	Optional	Read-only. Declared purpose; validated against the frozen category list.
version	number | undefined	Optional	Read-only. Protocol version, used to reject incompatible registrations.
description	string | undefined	Optional	Read-only. See the type definition and usage context.
terminal	boolean | undefined	Optional	Read-only. Marks a command that ends the interaction.
discriminator	{ readonly field: string; readonly value: string; } | undefined	Optional	Read-only. Constant field identifying the command; its value is forced to the command id.
fields	readonly string[] | Readonly<Record<string, ProtocolField>> | undefined	Optional	Read-only. Field declarations by name, or an ordered list of field names.
ownedFields	readonly string[] | undefined	Optional	Read-only. Fields the program writes; may name fields not declared in fields.
additionalProperties	boolean | undefined	Optional	Read-only. Whether fields outside the declaration are rejected; defaults to the compiler policy.
optionalPresence	"own" | "defined" | undefined	Optional	Read-only. 'defined' rejects an explicitly undefined optional property; 'own' preserves its presence.
modes	readonly string[] | undefined	Optional	Read-only. App-declared modes in which the command is available.
error	ProtocolReason<Value, Args> | undefined	Optional	Read-only. Rejection wording for the command as a whole.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to rejections from this command.
checks	readonly ProtocolCheck<Value, Args>[] | undefined	Optional	Read-only. Declarative rejection rules, evaluated in order after the structural checks.
refine	((value: Value, ...args: Args) => void) | undefined	Optional	Read-only. Domain checks/bindings only; invoked after structural and declarative checks.
format	((value: Value, ...args: Args) => Result) | undefined	Optional	Read-only. Formats the validated value into the command result.

Returns: Readonly<Record<Id, Command<Value, Result, Args>>>.

set

Instance method.

Install one compiled command during construction.

set(id: string, command: Command<Value, Result, Args>): CommandCatalog<Value, Result, Args, Id>

Install one compiled command during construction.

Parameter	Type	Passing	Description
id	string	Required	—
command	Command<Value, Result, Args>	Required	—

Fields of command

Field	Type	Required	Description
category	InteractionCategory | undefined	Optional	Read-only. See the type definition and usage context.
version	number | undefined	Optional	Read-only. See the type definition and usage context.
description	string | undefined	Optional	Read-only. See the type definition and usage context.
terminal	boolean | undefined	Optional	Read-only. See the type definition and usage context.
fieldSchemas	Record<string, unknown>	Required	Read-only. Per-field schemas, including the forced discriminator field.
modelJsonSchema	Record<string, unknown>	Required	Read-only. Schema for model output; only modelRequired fields are required here.
inputJsonSchema	Record<string, unknown>	Required	Read-only. Schema for runtime input; every required field is required here.
modes	readonly string[] | undefined	Optional	Read-only. See the type definition and usage context.
ownedFields	readonly string[]	Required	Read-only. Field names the program owns; the model must not supply them.
keys	(value: Record<string, unknown>) => string[]	Required	Selector values carried by value, used to resolve the command before parsing.
assert	(value: Value, ...args: Args) => void	Required	Validates without formatting; throws on the first failed check.
parse	(value: Value, ...args: Args) => Result	Required	Validates and returns the formatted result.

Returns: CommandCatalog<Value, Result, Args, Id>.

delete

Instance method.

Removal is not supported.

delete(_id: string): boolean

Removal is not supported.

Parameter	Type	Passing	Description
_id	string	Required	—

Returns: boolean.

clear

Instance method.

Clearing is not supported.

clear(): void

Clearing is not supported.

No call parameters.

Returns: void.

toRecord

Instance method.

Explicit dictionary projection; definitions always remains an ordered array.

toRecord(): Readonly<Record<Id, Command<Value, Result, Args>>>

Explicit dictionary projection; definitions always remains an ordered array.

No call parameters.

Returns: Readonly<Record<Id, Command<Value, Result, Args>>>.

manifest

Instance method.

The same declarations drive purpose-specific menus, documentation and handler binding.

manifest(category?: InteractionCategory): readonly InteractionDescriptor[]

The same declarations drive purpose-specific menus, documentation and handler binding.

Parameter	Type	Passing	Description
category	InteractionCategory | undefined	Optional	—

Returns: readonly InteractionDescriptor[].

parse

Instance method.

Validate and parse one payload as the named command.

Checks run before the command's own parser: the id must exist, the mode (when configured) must be allowed, and no other command may claim a field that this payload sets. The last rule prevents one command from silently consuming another command's data.

parse(id: string, value: Value, ...args: Args): Result

Validate and parse one payload as the named command.

Checks run before the command's own parser: the id must exist, the mode (when configured) must be allowed, and no other command may claim a field that this payload sets. The last rule prevents one command from silently consuming another command's data.

Parameter	Type	Passing	Description
id	string	Required	—
value	Value	Required	—
args	Args	Rest parameter	—

Returns: Result.

Awaited value: Awaited<Result>.

ids

Instance method.

ids(): readonly string[]

No call parameters.

Returns: readonly string[].

require

Instance method.

Look up a protocol that must exist.

require(id: string): Command<Value, Result, Args> & { readonly id: Id; }

Look up a protocol that must exist.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Command<Value, Result, Args> & { readonly id: Id; }.

Return value structure

Field	Type	Required	Description
category	InteractionCategory | undefined	Optional	Read-only. See the type definition and usage context.
version	number | undefined	Optional	Read-only. See the type definition and usage context.
description	string | undefined	Optional	Read-only. See the type definition and usage context.
terminal	boolean | undefined	Optional	Read-only. See the type definition and usage context.
fieldSchemas	Record<string, unknown>	Required	Read-only. Per-field schemas, including the forced discriminator field.
modelJsonSchema	Record<string, unknown>	Required	Read-only. Schema for model output; only modelRequired fields are required here.
inputJsonSchema	Record<string, unknown>	Required	Read-only. Schema for runtime input; every required field is required here.
modes	readonly string[] | undefined	Optional	Read-only. See the type definition and usage context.
ownedFields	readonly string[]	Required	Read-only. Field names the program owns; the model must not supply them.
keys	(value: Record<string, unknown>) => string[]	Required	Selector values carried by value, used to resolve the command before parsing.
assert	(value: Value, ...args: Args) => void	Required	Validates without formatting; throws on the first failed check.
parse	(value: Value, ...args: Args) => Result	Required	Validates and returns the formatted result.
id	Id	Required	Read-only. See the type definition and usage context.

Examples

• Interaction: declare commands and bind local handlers: The fields, purpose, selector, checks, and handler of a command come from one declaration; the model cannot add executable handlers.

First define one explanatory command and validate it

Beginner · Node.js

TypeScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
  commandField: 'type', commands: {
    reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } },
      checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
  },
});
console.log(protocol.receive({ type: 'reply', text: '普通对象也能实现接口。' }));
console.log(protocol.modelJsonSchema);

JavaScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
    commandField: 'type', commands: {
        reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } },
            checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
    },
});
console.log(protocol.receive({ type: 'reply', text: '普通对象也能实现接口。' }));
console.log(protocol.modelJsonSchema);

Keep the same protocol and add complete handler binding

Configuration · Node.js

TypeScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
  commandField: 'type', commands: {
    reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } }, checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
    unavailable: { category: 'receipt', description: '说明资料不可用', fields: {} },
  },
});
const dispatcher = Interaction.bind(protocol, {
  reply: value => '说明：' + String(value.text),
  unavailable: () => '资料暂不可用',
});
console.log(dispatcher.dispatch({ type: 'reply', text: '普通对象也能实现接口。' }, undefined));
console.log(dispatcher.catalog);

JavaScript

import { Interaction } from '@jangts/agent-core/kits/interaction';
const protocol = Interaction.define({
    commandField: 'type', commands: {
        reply: { category: 'presentation', description: '展示已确认说明', fields: { text: { required: true, jsonSchema: { type: 'string' } } }, checks: [{ occur: value => typeof value.text !== 'string', error: 'text 必须是字符串' }] },
        unavailable: { category: 'receipt', description: '说明资料不可用', fields: {} },
    },
});
const dispatcher = Interaction.bind(protocol, {
    reply: value => '说明：' + String(value.text),
    unavailable: () => '资料暂不可用',
});
console.log(dispatcher.dispatch({ type: 'reply', text: '普通对象也能实现接口。' }, undefined));
console.log(dispatcher.catalog);

Reuse the single-command and batch compilation entries directly

Extension · Node.js

When you use Interaction the selector is generated for you; when you use defineCommand yourself you may also supply discriminator explicitly. This example does not execute any tool.

TypeScript

import { defineCommand, compileCommands, commandSchema, CommandCatalog } from '@jangts/agent-core/kits/interaction';
const reply = defineCommand({ fields: { text: { required: true } }, checks: [{ occur: value => typeof value.text !== 'string', error: '需要文本' }] });
console.log(reply.parse({ text: '接口说明' }));
const compiled = compileCommands({ reply: { fields: { text: { required: true } } } });
const commands = new CommandCatalog(Object.entries(compiled));
console.log(commandSchema('reply', commands.require('reply')), commands.manifest());

JavaScript

import { defineCommand, compileCommands, commandSchema, CommandCatalog } from '@jangts/agent-core/kits/interaction';
const reply = defineCommand({ fields: { text: { required: true } }, checks: [{ occur: value => typeof value.text !== 'string', error: '需要文本' }] });
console.log(reply.parse({ text: '接口说明' }));
const compiled = compileCommands({ reply: { fields: { text: { required: true } } } });
const commands = new CommandCatalog(Object.entries(compiled));
console.log(commandSchema('reply', commands.require('reply')), commands.manifest());

Related policy source

• Fields, checks, and the model Schema
• Selectors and command receiving
• Bind local handlers by validated command

Related definitions

• Command
• CommandCatalogOptions
• defineCommandCatalog
• InteractionCategory
• InteractionDescriptor
• ProtocolRegistry