Reflection

KIT · constant · Runtime value

Import

TypeScript

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

JavaScript

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

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

Definition

Member index

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

Member details

defineReflection

Reflection.defineReflection<App>(definition: ReflectionDefinition<App>): ReflectionTask<App>

Compile a reflection task.

Model-driven investigation through ordinary registered tools and the existing Core loop. The task always reports persisted: false: storing a report is the App's decision. Observed findings must cite evidence ids that were actually returned in this run, which is what keeps the report tied to real observations instead of model recall.

Type parameter	Constraint	Default type
App	—	—

Parameter	Type	Passing	Description
definition	ReflectionDefinition<App>	Required	—

Fields of definition

Field	Type	Required	Description
model	Pick<ModelRunner<string, readonly ModelTransportDefinition<unknown>[]>, "remainingCalls" | "createChild">	Required	Read-only. Parent runner; the reflection creates a child and preserves the parent's reserve.
source	ReflectionSource<App>	Required	Read-only. Evidence source queried through the reflection tools.
tools	readonly ToolDefinition<any, any, App>[] | undefined	Optional	Read-only. Additional tools exposed to the reflection model.
maxCalls	number | undefined	Optional	Read-only. Model calls the child may use; defaults to 4.
reserveCalls	number | undefined	Optional	Read-only. Parent calls kept untouched; defaults to 1.
timeoutMs	number | undefined	Optional	Read-only. Wall-clock limit for the whole reflection in milliseconds; defaults to 30000.
maxPages	number | undefined	Optional	Read-only. Maximum evidence pages read; defaults to 4.
maxEvents	number | undefined	Optional	Read-only. Maximum evidence items collected; defaults to 64.
maxEvidenceChars	number | undefined	Optional	Read-only. Maximum evidence characters placed in the model context; defaults to 12000.
authorize	(question: string, context: OperationContext<App>) => MaybePromise<void>	Required	Guards one reflection request; runs before any model call.

Returns: ReflectionTask<App>.

Return value structure

Field	Type	Required	Description
run	(question: string, context: OperationContext<App>) => Promise<ReflectionReport>	Required	Answers the question from evidence; never throws for incomplete evidence alone.

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

• defineReflection
• ReflectionDefinition
• ReflectionTask