Answering

KIT · constant · Runtime value

Import

TypeScript

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

JavaScript

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

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

Definition

Member index

Member	Purpose
defineAnswerTaskCatalog	See the overload below for full inputs and outputs.
defineAnswerReaderCatalog	See the overload below for full inputs and outputs.
defineAnswerCheckCatalog	See the overload below for full inputs and outputs.
defineAnswerFlow	See the overload below for full inputs and outputs.
validateAnswerBatch	See the overload below for full inputs and outputs.

Member details

defineAnswerTaskCatalog

Answering.defineAnswerTaskCatalog<Input, Evidence, App, Data = unknown>(definitions: readonly AnswerTaskDefinition<Input, Data>[], ports: AnswerTaskPorts<Input, Evidence, App, Data>): Readonly<{ describe: () => { inputJsonSchema: Readonly<Record<string, unknown>>; id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; metadata: Data; }[]; read(request: { taskId: string; input: unknown; }, context: OperationContext<App>): Evidence; readAsync(request: { taskId: string; input: unknown; }, context: OperationContext<App>): Promise<Evidence>; definitions: readonly Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>[]; ids(): readonly string[]; values(): IterableIterator<Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>>; entries(): IterableIterator<readonly [string, Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>]>; has(id: string): boolean; get(id: string): Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }> | undefined; require(id: string): Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>; }>

Compile the answer task catalog from its declarations and shared ports.

Task ids, schemas, readers, outputs and checks have one compiled authority: a task can only reference a reader or check that the ports actually registered, and metadata is cloned and frozen so later mutation by the caller cannot change a registered task.

Type parameter	Constraint	Default type
Input	—	—
Evidence	—	—
App	—	—
Data	—	unknown

Parameter	Type	Passing	Description
definitions	readonly AnswerTaskDefinition<Input, Data>[]	Required	—
ports	AnswerTaskPorts<Input, Evidence, App, Data>	Required	—

Fields of ports

Field	Type	Required	Description
readers	ReadonlyCatalog<AnswerReader<Input, Evidence, App, Data>>	Required	Read-only. See the type definition and usage context.
outputs	ReadonlyCatalog<{ readonly id: string; }>	Required	Read-only. See the type definition and usage context.
checks	ReadonlyCatalog<{ readonly id: string; }>	Required	Read-only. See the type definition and usage context.
assertDefinition	((task: Readonly<AnswerTaskDefinition<Input, Data>>) => void) | undefined	Optional	Extra App assertion over a raw definition, before it is compiled.

Returns: Readonly<{ describe: () => { inputJsonSchema: Readonly<Record<string, unknown>>; id: string; description: string; readerId: string; outputId: string; scopeId: string \| undefined; goalIds: readonly any[]; checkIds: readonly any[]; metadata: Data; }[]; read(request: { taskId: string; input: unknown; }, context: OperationContext<App>): Evidence; readAsync(request: { taskId: string; input: unknown; }, context: OperationContext<App>): Promise<Evidence>; definitions: readonly Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string \| undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>[]; ids(): readonly string[]; values(): IterableIterator<Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string \| undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>>; entries(): IterableIterator<readonly [string, Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string \| undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>]>; has(id: string): boolean; get(id: string): Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string \| undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }> \| undefined; require(id: string): Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string \| undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>; }>.

Return value structure

Field	Type	Required	Description
describe	() => { inputJsonSchema: Readonly<Record<string, unknown>>; id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; metadata: Data; }[]	Required	Task metadata with the JSON schema flattened for model or admin presentation.
read	(request: { taskId: string; input: unknown; }, context: OperationContext<App>) => Evidence	Required	Read evidence through a task's registered reader, synchronously.
readAsync	(request: { taskId: string; input: unknown; }, context: OperationContext<App>) => Promise<Evidence>	Required	Read evidence through a task's registered reader, awaiting an async reader.
definitions	readonly Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<{ id: string; description: string; readerId: string; outputId: string; scopeId: string | undefined; goalIds: readonly any[]; checkIds: readonly any[]; inputSchema: SchemaAdapter<Input>; metadata: Data; }>	Required	Returns the definition or throws; use when the id is a required reference.

defineAnswerReaderCatalog

Answering.defineAnswerReaderCatalog<Input, Evidence, App, Data = unknown>(definitions: readonly AnswerReader<Input, Evidence, App, Data>[]): ReadonlyCatalog<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }>

Compile a reader catalog.

Type parameter	Constraint	Default type
Input	—	—
Evidence	—	—
App	—	—
Data	—	unknown

Parameter	Type	Passing	Description
definitions	readonly AnswerReader<Input, Evidence, App, Data>[]	Required	—

Returns: ReadonlyCatalog<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }>.

Return value structure

Field	Type	Required	Description
definitions	readonly Readonly<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<{ id: string; read: (input: Input, context: OperationContext<App> & { readonly task: Readonly<AnswerTaskDefinition<Input, Data>>; }) => MaybePromise<Evidence>; }>	Required	Returns the definition or throws; use when the id is a required reference.

defineAnswerCheckCatalog

Answering.defineAnswerCheckCatalog<Value, App>(definitions: readonly AnswerChecker<Value, App>[]): Readonly<{ check(request: { checkIds: readonly string[]; value: Value; }, context: OperationContext<App>): AnswerCheck<Value>; definitions: readonly Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>[]; ids(): readonly string[]; values(): IterableIterator<Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>>; entries(): IterableIterator<readonly [string, Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>]>; has(id: string): boolean; get(id: string): Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }> | undefined; require(id: string): Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>; }>

Compile a checker catalog.

A checker may return a replacement value; it is threaded into the next checker, so the selected ids behave like an ordered chain rather than independent assertions.

Type parameter	Constraint	Default type
Value	—	—
App	—	—

Parameter	Type	Passing	Description
definitions	readonly AnswerChecker<Value, App>[]	Required	—

Returns: Readonly<{ check(request: { checkIds: readonly string[]; value: Value; }, context: OperationContext<App>): AnswerCheck<Value>; definitions: readonly Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>[]; ids(): readonly string[]; values(): IterableIterator<Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>>; entries(): IterableIterator<readonly [string, Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>]>; has(id: string): boolean; get(id: string): Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }> \| undefined; require(id: string): Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>; }>.

Return value structure

Field	Type	Required	Description
check	(request: { checkIds: readonly string[]; value: Value; }, context: OperationContext<App>) => AnswerCheck<Value>	Required	See the type definition and usage context.
definitions	readonly Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	() => IterableIterator<Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<{ id: string; check: (value: Value, context: OperationContext<App>) => CheckResult<Value>; }>	Required	Returns the definition or throws; use when the id is a required reference.

defineAnswerFlow

Answering.defineAnswerFlow<Data, Value, App = undefined>(definition: AnswerFlowDefinition<Data, Value, App>): Readonly<{ run(request: { inputIds: readonly string[]; items: readonly AnswerItem<Data>[]; }, context: OperationContext<App>): Promise<AnswerResult<Data, Value>[]>; }>

Compile a reusable answer workflow.

Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned. The flow runs at most maxRepairs + 1 rounds: one generation pass, then one repair round per failing item set, and finally an explicit accepted/fallback/blocked result per item.

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

Parameter	Type	Passing	Description
definition	AnswerFlowDefinition<Data, Value, App>	Required	—

Fields of definition

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> | undefined; }, 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.

Returns: Readonly<{ run(request: { inputIds: readonly string[]; items: readonly AnswerItem<Data>[]; }, context: OperationContext<App>): Promise<AnswerResult<Data, Value>[]>; }>.

Return value structure

Field	Type	Required	Description
run	(request: { inputIds: readonly string[]; items: readonly AnswerItem<Data>[]; }, context: OperationContext<App>) => Promise<AnswerResult<Data, Value>[]>	Required	Run one answer batch.

validateAnswerBatch

Answering.validateAnswerBatch<Data>(inputIds: readonly string[], items: readonly AnswerItem<Data>[], maxItems: number): void

Validate that one batch is well formed and fully covered.

Type parameter	Constraint	Default type
Data	—	—

Parameter	Type	Passing	Description
inputIds	readonly string[]	Required	—
items	readonly AnswerItem<Data>[]	Required	—
maxItems	number	Required	—

Returns: void.

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

First validate multi-question coverage to avoid missing inputs

Extension · Node.js

TypeScript

import { Answering } from '@jangts/agent-core/kits/answering';
const items = [
  { id: 'define', inputIds: ['q1'], sourceStatus: 'ready' as const, data: { source: '定义节点' } },
  { id: 'run', inputIds: ['q2'], sourceStatus: 'unavailable' as const, data: { source: '' } },
];
Answering.validateAnswerBatch(['q1', 'q2'], items, 4);
console.log('两个问题均有明确处理项，包括资料不可用的项。');

JavaScript

import { Answering } from '@jangts/agent-core/kits/answering';
const items = [
    { id: 'define', inputIds: ['q1'], sourceStatus: 'ready', data: { source: '定义节点' } },
    { id: 'run', inputIds: ['q2'], sourceStatus: 'unavailable', data: { source: '' } },
];
Answering.validateAnswerBatch(['q1', 'q2'], items, 4);
console.log('两个问题均有明确处理项，包括资料不可用的项。');

Related policy source

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

Related definitions

• AnswerChecker
• AnswerFlowDefinition
• AnswerItem
• AnswerReader
• AnswerTaskDefinition
• AnswerTaskPorts
• defineAnswerCheckCatalog
• defineAnswerFlow
• defineAnswerReaderCatalog
• defineAnswerTaskCatalog
• ReadonlyCatalog
• validateAnswerBatch