ReflectionSource

KIT · interface · Type contract

App-owned evidence source, including its own authorization.

Import

TypeScript

import type { ReflectionSource } from '@jangts/agent-core/kits/reflection';

JavaScript

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

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

Definition

interface ReflectionSource<App>

Type parameters

Type parameter	Constraint	Default type
App	—	—

Field 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.
authorize	(query: ReflectionQuery, context: OperationContext<App>) => MaybePromise<void>	Required	Guards one query; runs before any evidence is read.
query	(query: ReflectionQuery, context: OperationContext<App>) => Promise<ReflectionPage>	Required	Returns one page; an invalid page shape aborts the reflection.

Member index

Member	Purpose
authorize	Guards one query; runs before any evidence is read.
query	Returns one page; an invalid page shape aborts the reflection.

Member details

authorize

Guards one query; runs before any evidence is read.

ReflectionSource.authorize(query: ReflectionQuery, context: OperationContext<App>): MaybePromise<void>

Guards one query; runs before any evidence is read.

Parameter	Type	Passing	Description
query	ReflectionQuery	Required	—
context	OperationContext<App>	Required	—

Fields of query

Field	Type	Required	Description
run	string | undefined	Optional	Read-only. Run to inspect; omitted means the App chooses the scope.
types	readonly string[] | undefined	Optional	Read-only. Evidence types to include; omitted means all types.
cursor	string | undefined	Optional	Read-only. Opaque continuation cursor from a previous page.
limit	number	Required	Read-only. Maximum items requested; at least 1, clamped to the remaining evidence budget.

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: MaybePromise<void>.

Awaited value: void.

query

Returns one page; an invalid page shape aborts the reflection.

ReflectionSource.query(query: ReflectionQuery, context: OperationContext<App>): Promise<ReflectionPage>

Returns one page; an invalid page shape aborts the reflection.

Parameter	Type	Passing	Description
query	ReflectionQuery	Required	—
context	OperationContext<App>	Required	—

Fields of query

Field	Type	Required	Description
run	string | undefined	Optional	Read-only. Run to inspect; omitted means the App chooses the scope.
types	readonly string[] | undefined	Optional	Read-only. Evidence types to include; omitted means all types.
cursor	string | undefined	Optional	Read-only. Opaque continuation cursor from a previous page.
limit	number	Required	Read-only. Maximum items requested; at least 1, clamped to the remaining evidence budget.

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<ReflectionPage>.

Awaited value: ReflectionPage.

Return value structure

Field	Type	Required	Description
items	readonly ReflectionEvidence[]	Required	Read-only. Items in source order.
cursor	string | undefined	Optional	Read-only. Continuation cursor; absent when the source has no further items.
coverage	{ readonly consistency: "best-effort" | "snapshot"; readonly complete: boolean | null; readonly gaps: readonly string[]; }	Required	Read-only. See the type definition and usage context.

Examples

• Log reflection: authorization metadata and evidence reports: The App supplies authorized evidence sources; the reflection task produces a sourced report through ordinary model and tool contracts.

Bind the reflection model, evidence source, and authorization

Beginner · Node.js

TypeScript

import { defineReflection } from '@jangts/agent-core/kits/reflection';
import type { ReflectionSource } from '@jangts/agent-core/kits/reflection';
import type { ModelRunner, OperationContext } from '@jangts/agent-core';

export function review<App>(model: ModelRunner, source: ReflectionSource<App>,
  authorize: (question: string, context: OperationContext<App>) => Promise<void>) {
  return defineReflection({ model, source, authorize,
    maxCalls: 4, reserveCalls: 1, maxPages: 4, maxEvents: 64, maxEvidenceChars: 12000 });
}

JavaScript

import { defineReflection } from '@jangts/agent-core/kits/reflection';
export function review(model, source, authorize) {
    return defineReflection({ model, source, authorize,
        maxCalls: 4, reserveCalls: 1, maxPages: 4, maxEvents: 64, maxEvidenceChars: 12000 });
}

Build the same kind of evidence source from a log reader

Configuration · Node.js

The reader's directory scope, shutdown, and retention are managed by the App. The adapted source can be passed into the same defineReflection.

TypeScript

import { defineReflectionLogSource } from '@jangts/agent-core/kits/reflection';
import type { ReflectionLogReader } from '@jangts/agent-core/kits/reflection';
import type { OperationContext } from '@jangts/agent-core';

export function logSource<App>(reader: ReflectionLogReader, traceId: string,
  authorize: (context: OperationContext<App>) => Promise<void>) {
  return defineReflectionLogSource({ reader, traceId, id: 'authorized-history', authorize });
}

JavaScript

import { defineReflectionLogSource } from '@jangts/agent-core/kits/reflection';
export function logSource(reader, traceId, authorize) {
    return defineReflectionLogSource({ reader, traceId, id: 'authorized-history', authorize });
}

Related policy source

• Reflection evidence references and report checks

Related definitions

• MaybePromise
• OperationContext
• ReflectionPage
• ReflectionQuery