CandidateSelectionDefinition

KIT · interface · Type contract

Declares the alternative-proposal envelope.

A value without the declared field is treated as a single implicit candidate.

Import

TypeScript

import type { CandidateSelectionDefinition } from '@jangts/agent-core/kits/candidates';

JavaScript

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

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

Definition

interface CandidateSelectionDefinition

Field structure

Field	Type	Required	Description
field	string	Required	Read-only. Reply field that carries the alternatives.
minCandidates	number | undefined	Optional	Read-only. Minimum number of distinct candidates once the envelope is present; defaults to 1.
maxCandidates	number	Required	Read-only. Maximum number of candidates; must be a safe integer not below the minimum.
error	BreakReason | undefined	Optional	Read-only. Rejection wording, either fixed, a pre-built error or a lazy factory.
tags	readonly string[] | undefined	Optional	Read-only. Diagnostic tags attached to every rejection from this contract.

Examples

• Candidates: a bounded candidate envelope: The same result can be a single proposal or a candidate list; candidate permission and count are controlled by the application.

Accept a single proposal or up to three candidates

Beginner · Node.js

TypeScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', maxCandidates: 3 });
console.log(selection.parse({ value: { action: 'read' }, allowed: true }));
console.log(selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: true }));

JavaScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', maxCandidates: 3 });
console.log(selection.parse({ value: { action: 'read' }, allowed: true }));
console.log(selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: true }));

Add a lower bound and an application-stage constraint to the same parse

Configuration · Node.js

TypeScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', minCandidates: 2, maxCandidates: 3, error: '当前阶段不接受这份候选' });
const taskAccepted = true;
try {
  selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: !taskAccepted });
} catch (error) { console.log((error as Error).message); }

JavaScript

import { Candidates } from '@jangts/agent-core/kits/candidates';
const selection = Candidates.defineCandidateSelection({ field: 'candidates', minCandidates: 2, maxCandidates: 3, error: '当前阶段不接受这份候选' });
const taskAccepted = true;
try {
    selection.parse({ value: { candidates: [{ action: 'read' }, { action: 'reply' }] }, allowed: !taskAccepted });
}
catch (error) {
    console.log(error.message);
}

Related policy source

• Candidate envelope, count, and shallow constraints

Related definitions

• BreakReason