Retrieval

KIT · constant · Runtime value

Import

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';

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

Definition

Member index

Member	Purpose
defineRetrieval	See the overload below for full inputs and outputs.
retrievalQueryKey	See the overload below for full inputs and outputs.

Member details

defineRetrieval

Retrieval.defineRetrieval<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, App>(definition: RetrievalDefinition<Query, Source, Result, App>): RetrievalRunner<Query, Source, Result, import("../structs/common.js").OperationContext<App>>

Compile a retrieval runner from its declared ports and effects.

Rejected queries stay in the caller's seen set, so a retry is reported as a duplicate instead of silently repeating the adapter call; only successful results increment the query count.

Type parameter	Constraint	Default type
Query	—	—
Source	RetrievalSource	—
Result	RetrievalResult<Source>	—
App	—	—

Parameter	Type	Passing	Description
definition	RetrievalDefinition<Query, Source, Result, App>	Required	—

Fields of definition

Field	Type	Required	Description
id	string	Required	Read-only. See the type definition and usage context.
description	string	Required	Read-only. See the type definition and usage context.
tags	readonly string[] | undefined	Optional	Read-only. See the type definition and usage context.
prepare	((query: Query, context: OperationContext<App>) => Query) | undefined	Optional	Read-only. Normalizes the query before assertions run; must be synchronous.
assertInput	(query: Query, context: OperationContext<App>) => void	Required	Read-only. Rejects a malformed query; must be synchronous and return void.
state	(context: OperationContext<App>) => RetrievalState<Source>	Required	Read-only. Returns the request-owned state that holds counters and sources.
limit	(context: OperationContext<App>) => number	Required	Read-only. Maximum accepted queries for the current state.
key	((query: Query) => string) | undefined	Optional	Read-only. Deduplication key; defaults to a canonical serialization of the query.
errors	{ readonly duplicate?: RetrievalReason<Query, OperationContext<App>> | undefined; readonly budget?: RetrievalReason<Query, OperationContext<App>> | undefined; } | undefined	Optional	Read-only. See the type definition and usage context.
authorize	((query: Query, context: OperationContext<App>) => void) | undefined	Optional	Read-only. Resource authorization runs after duplicate/budget checks and before reserving a key.
execute	(query: Query, context: OperationContext<App>) => Result	Required	Read-only. Performs the actual read; must be synchronous. Throwing does not refund the query key.
assertResult	((result: Result, query: Query, context: OperationContext<App>) => void) | undefined	Optional	Read-only. Validates the adapter result; a throw leaves the query counted as seen but not successful.
sourceId	((source: Source, query: Query, sequence: number, context: OperationContext<App>) => string) | undefined	Optional	Read-only. Names a source; the assigned value replaces sourceId in the receipt result.
effects	readonly RetrievalEffect<Query, Source, Result, OperationContext<App>>[] | undefined	Optional	Read-only. See the type definition and usage context.
now	(() => number) | undefined	Optional	Read-only. Clock override for receipt timestamps; defaults to Date.now.

Returns: RetrievalRunner<Query, Source, Result, OperationContext<App>>.

Return value structure

Field	Type	Required	Description
id	string	Required	Read-only. See the type definition and usage context.
description	string	Required	Read-only. See the type definition and usage context.
effects	readonly RetrievalEffect<Query, Source, Result, OperationContext<App>>[]	Required	Read-only. Effects that run after every accepted query.
run	(input: Query, context: OperationContext<App>) => RetrievalReceipt<Query, Source, Result>	Required	Executes one query in the fixed lifecycle order and returns its receipt.

retrievalQueryKey

Retrieval.retrievalQueryKey(value: unknown): string

Serialize a query into a stable structural key.

Object keys are sorted recursively while array positions are preserved. Values that JSON cannot represent, such as functions or undefined, make JSON.stringify return undefined and therefore produce an error instead of a colliding key.

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: string.

Examples

• Retrieval: a synchronous retrieval lifecycle with quota: Keep normalization, validation, deduplication, authorization, reading, and follow-up effects on one deterministic call path.

Configure one read for the same product material

Beginner · Node.js

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
  id: 'manual-search', description: '读取已确认的本地演示资料',
  assertInput(query: string) { if (!query.trim()) throw new Error('查询为空'); },
  state: () => state, limit: () => 2,
  execute: (query: string) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
    id: 'manual-search', description: '读取已确认的本地演示资料',
    assertInput(query) { if (!query.trim())
        throw new Error('查询为空'); },
    state: () => state, limit: () => 2,
    execute: (query) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);

Add normalization, authorization, and receipt effects to the same run

Configuration · Node.js

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const retrieval = Retrieval.defineRetrieval<string, Source, { sources: Source[] }, { canRead: boolean }>({
  id: 'manual-search', description: '按当前服务端权限读取资料',
  prepare: query => query.trim(),
  assertInput(query) { if (!query) throw new Error('查询为空'); },
  state: () => state, limit: () => 2,
  authorize(_query, { app }) { if (!app.canRead) throw new Error('没有资料读取权限'); },
  execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
  effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const retrieval = Retrieval.defineRetrieval({
    id: 'manual-search', description: '按当前服务端权限读取资料',
    prepare: query => query.trim(),
    assertInput(query) { if (!query)
        throw new Error('查询为空'); },
    state: () => state, limit: () => 2,
    authorize(_query, { app }) { if (!app.canRead)
        throw new Error('没有资料读取权限'); },
    execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
    effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);

Related policy source

• Deduplication, reservation, reading, counting, and effect order
• Default query key

Related definitions

• defineRetrieval
• OperationContext
• RetrievalDefinition
• retrievalQueryKey
• RetrievalRunner