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.

parse({value,allowed}) returns unknown[]. Input without the configured field is returned as a single item; when field is present the input must be an object with only that field, its members must be non-array objects, and they cannot nest the candidate field again. The default is minCandidates=1 and maxCandidates is required. allowed only says whether multiple candidates are accepted here, not that execution is authorized; a model cannot bypass restrictions that apply after a task is accepted through a candidate envelope.

Progressive examples for the same business case

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);
}

Policies & implementations

• Candidate envelope, count, and shallow constraints