AnswerFlowDefinition

KIT · interface · Type contract

Static handlers and limits; signal, diagnostics and App dependencies arrive at run.

Import

TypeScript

import type { AnswerFlowDefinition } from '@jangts/agent-core/kits/answering';

JavaScript

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

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

Definition

interface AnswerFlowDefinition<Data, Value, App>

Type parameters

Type parameter	Constraint	Default type
Data	—	—
Value	—	—
App	—	undefined

Field structure

Field	Type	Required	Description
maxItems	number	Required	Read-only. Maximum items in one batch; must be a positive integer.
maxRepairs	number	Required	Read-only. Repair rounds; the flow runs at most maxRepairs + 1 rounds in total.
reviewPolicy	"required" | "off" | "optional" | undefined	Optional	Read-only. Review policy; defaults to optional, required blocks on an unresolved review.
canInvoke	(context: OperationContext<App>) => boolean	Required	Request-level budget guard; must return boolean synchronously.
generate	(input: { readonly items: readonly AnswerItem<Data>[]; readonly repairs?: ReadonlyMap<string, readonly AnswerIssue[]>; readonly previous?: ReadonlyMap<string, Value>; }, context: OperationContext<App>) => Promise<ReadonlyMap<string, Value>>	Required	Produces values for the items that still need one. repairs carries the issues of a failed attempt and previous its rejected values.
check	(input: { readonly item: AnswerItem<Data>; readonly value: Value; }, context: OperationContext<App>) => AnswerCheck<Value>	Required	Local check for one generated value; must return synchronously.
review	((input: { readonly items: readonly { item: AnswerItem<Data>; value: Value; }[]; }, context: OperationContext<App>) => Promise<ReadonlyMap<string, AnswerCheck<Value>>>) | undefined	Optional	Batch review; returns one check per reviewed item and must cover the submitted items.
fallback	(input: { readonly item: AnswerItem<Data>; readonly issues: readonly AnswerIssue[]; }, context: OperationContext<App>) => RecoveryResult<Value>	Required	Last resort for a failed item; handled supplies a replacement value.
observe	((input: { readonly stageId: string; readonly results: readonly AnswerResult<Data, Value>[]; }, context: OperationContext<App>) => MaybePromise<void>) | undefined	Optional	Observes a stage outcome; failures must not affect the flow result.

Member index

Member	Purpose
canInvoke	Request-level budget guard; must return boolean synchronously.
generate	Produces values for the items that still need one. repairs carries the issues of a failed attempt and previous its rejected values.
check	Local check for one generated value; must return synchronously.
fallback	Last resort for a failed item; handled supplies a replacement value.

Member details

canInvoke

Request-level budget guard; must return boolean synchronously.

AnswerFlowDefinition.canInvoke(context: OperationContext<App>): boolean

Request-level budget guard; must return boolean synchronously.

Parameter	Type	Passing	Description
context	OperationContext<App>	Required	—

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: boolean.

generate

Produces values for the items that still need one.

repairs carries the issues of a failed attempt and previous its rejected values.

AnswerFlowDefinition.generate(input: { readonly items: readonly AnswerItem<Data>[]; readonly repairs?: ReadonlyMap<string, readonly AnswerIssue[]>; readonly previous?: ReadonlyMap<string, Value>; }, context: OperationContext<App>): Promise<ReadonlyMap<string, Value>>

Produces values for the items that still need one.

repairs carries the issues of a failed attempt and previous its rejected values.

Parameter	Type	Passing	Description
input	{ readonly items: readonly AnswerItem<Data>[]; readonly repairs?: ReadonlyMap<string, readonly AnswerIssue[]>; readonly previous?: ReadonlyMap<string, Value>; }	Required	—
context	OperationContext<App>	Required	—

Fields of input

Field	Type	Required	Description
items	readonly AnswerItem<Data>[]	Required	Read-only. See the type definition and usage context.
repairs	ReadonlyMap<string, readonly AnswerIssue[]> | undefined	Optional	Read-only. See the type definition and usage context.
previous	ReadonlyMap<string, Value> | undefined	Optional	Read-only. See the type definition and usage context.

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: Promise<ReadonlyMap<string, Value>>.

Awaited value: ReadonlyMap<string, Value>.

check

Local check for one generated value; must return synchronously.

AnswerFlowDefinition.check(input: { readonly item: AnswerItem<Data>; readonly value: Value; }, context: OperationContext<App>): AnswerCheck<Value>

Local check for one generated value; must return synchronously.

Parameter	Type	Passing	Description
input	{ readonly item: AnswerItem<Data>; readonly value: Value; }	Required	—
context	OperationContext<App>	Required	—

Fields of input

Field	Type	Required	Description
item	AnswerItem<Data>	Required	Read-only. See the type definition and usage context.
value	Value	Required	Read-only. See the type definition and usage context.

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: AnswerCheck<Value>.

Return value structure

Field	Type	Required	Description
status	"unavailable" | "passed" | "failed" | "not-run"	Required	Read-only. See the type definition and usage context.
issues	readonly Issue[]	Required	Read-only. Problems found; expected to be empty when the status is passed.
value	Value | undefined	Optional	Read-only. Checked or produced value; present only when the check yields one.

fallback

Last resort for a failed item; handled supplies a replacement value.

AnswerFlowDefinition.fallback(input: { readonly item: AnswerItem<Data>; readonly issues: readonly AnswerIssue[]; }, context: OperationContext<App>): RecoveryResult<Value>

Last resort for a failed item; handled supplies a replacement value.

Parameter	Type	Passing	Description
input	{ readonly item: AnswerItem<Data>; readonly issues: readonly AnswerIssue[]; }	Required	—
context	OperationContext<App>	Required	—

Fields of input

Field	Type	Required	Description
item	AnswerItem<Data>	Required	Read-only. See the type definition and usage context.
issues	readonly AnswerIssue[]	Required	Read-only. See the type definition and usage context.

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: RecoveryResult<Value>.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
handled	false	Required	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
handled	true	Required	Read-only. See the type definition and usage context.
value	Value	Required	Read-only. See the type definition and usage context.

Examples

• Answering Flow: item-by-item generation, review, and local repair: Preserve coverage relationships over a split question batch and repair failing items without regenerating the ones that passed.

First handle one question that has a source

Beginner · Node.js

The offline example uses already-read body text directly to show the flow contract; when switching to model generation, the same generate port still applies.

TypeScript

import { Answering } from '@jangts/agent-core/kits/answering';
const flow = Answering.defineAnswerFlow<{ source: string }, string, {}>({
  maxItems: 4, maxRepairs: 0, reviewPolicy: 'off', canInvoke: () => true,
  async generate({ items }) { return new Map(items.map(item => [item.id, item.data.source])); },
  check: ({ value }) => ({ status: value.trim() ? 'passed' : 'failed', issues: [] }),
  fallback: () => ({ handled: false }),
});
const result = await flow.run({ inputIds: ['question-1'], items: [{ id: 'explain', inputIds: ['question-1'], sourceStatus: 'ready', data: { source: '普通对象可以实现节点合同。' } }] }, { app: {}, signal: new AbortController().signal });
console.log(result[0].status, result[0].value);

JavaScript

import { Answering } from '@jangts/agent-core/kits/answering';
const flow = Answering.defineAnswerFlow({
    maxItems: 4, maxRepairs: 0, reviewPolicy: 'off', canInvoke: () => true,
    async generate({ items }) { return new Map(items.map(item => [item.id, item.data.source])); },
    check: ({ value }) => ({ status: value.trim() ? 'passed' : 'failed', issues: [] }),
    fallback: () => ({ handled: false }),
});
const result = await flow.run({ inputIds: ['question-1'], items: [{ id: 'explain', inputIds: ['question-1'], sourceStatus: 'ready', data: { source: '普通对象可以实现节点合同。' } }] }, { app: {}, signal: new AbortController().signal });
console.log(result[0].status, result[0].value);

Keep run unchanged and add review plus one local repair

Configuration · Node.js

The example triggers one real local repair with an empty draft; production review should rely on real evidence instead of substituting string equality for semantic review.

TypeScript

import { Answering } from '@jangts/agent-core/kits/answering';
const flow = Answering.defineAnswerFlow<{ source: string }, string, {}>({
  maxItems: 4, maxRepairs: 1, reviewPolicy: 'required', canInvoke: () => true,
  async generate({ items, repairs }) { return new Map(items.map(item => [item.id, repairs?.has(item.id) ? item.data.source : ''])); },
  check: ({ value }) => ({ status: value.trim() ? 'passed' : 'failed', issues: value.trim() ? [] : [{ code: 'EMPTY', message: '需要非空回答' }] }),
  async review({ items }) { return new Map(items.map(({ item, value }) => [item.id, { status: value === item.data.source ? 'passed' as const : 'failed' as const, issues: [] }])); },
  fallback: () => ({ handled: true, value: '当前资料不足，暂时无法回答。' }),
});
const result = await flow.run({ inputIds: ['question-1'], items: [{ id: 'explain', inputIds: ['question-1'], sourceStatus: 'ready', data: { source: '普通对象可以实现节点合同。' } }] }, { app: {}, signal: new AbortController().signal });
console.log(result[0].status, result[0].checks);

JavaScript

import { Answering } from '@jangts/agent-core/kits/answering';
const flow = Answering.defineAnswerFlow({
    maxItems: 4, maxRepairs: 1, reviewPolicy: 'required', canInvoke: () => true,
    async generate({ items, repairs }) { return new Map(items.map(item => [item.id, repairs?.has(item.id) ? item.data.source : ''])); },
    check: ({ value }) => ({ status: value.trim() ? 'passed' : 'failed', issues: value.trim() ? [] : [{ code: 'EMPTY', message: '需要非空回答' }] }),
    async review({ items }) { return new Map(items.map(({ item, value }) => [item.id, { status: value === item.data.source ? 'passed' : 'failed', issues: [] }])); },
    fallback: () => ({ handled: true, value: '当前资料不足，暂时无法回答。' }),
});
const result = await flow.run({ inputIds: ['question-1'], items: [{ id: 'explain', inputIds: ['question-1'], sourceStatus: 'ready', data: { source: '普通对象可以实现节点合同。' } }] }, { app: {}, signal: new AbortController().signal });
console.log(result[0].status, result[0].checks);

Related policy source

• Generation, checks, review, local repair, and delivery
• Question coverage checks

Related definitions

• AnswerCheck
• AnswerIssue
• AnswerItem
• AnswerResult
• MaybePromise
• OperationContext
• RecoveryResult