ReflectionLogReader

KIT · interface · Type contract

Structural port: the App supplies its own FileLogReader, trusted scope and current authorization.

Import

TypeScript

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

JavaScript

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

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

Definition

interface ReflectionLogReader

Field structure

Field	Type	Required	Description
listRuns	(query: { traceId?: string; cursor?: string; limit?: number; signal?: AbortSignal; }) => Promise<Page<{ path: string; manifest: Readonly<Record<string, unknown>>; }>>	Required	List runs the caller may inspect.
readEvents	(query: { run: string; sources?: readonly ("app" | "core" | "client")[]; types?: readonly string[]; cursor?: string; limit?: number; signal?: AbortSignal; }) => Promise<Page<Record<string, unknown>>>	Required	Read the events of one run.

Member index

Member	Purpose
listRuns	List runs the caller may inspect.
readEvents	Read the events of one run.

Member details

listRuns

List runs the caller may inspect.

ReflectionLogReader.listRuns(query: { traceId?: string; cursor?: string; limit?: number; signal?: AbortSignal; }): Promise<Page<{ path: string; manifest: Readonly<Record<string, unknown>>; }>>

List runs the caller may inspect.

Parameter	Type	Passing	Description
query	{ traceId?: string; cursor?: string; limit?: number; signal?: AbortSignal; }	Required	—

Fields of query

Field	Type	Required	Description
traceId	string | undefined	Optional	See the type definition and usage context.
cursor	string | undefined	Optional	See the type definition and usage context.
limit	number | undefined	Optional	See the type definition and usage context.
signal	AbortSignal | undefined	Optional	See the type definition and usage context.

Returns: Promise<Page<{ path: string; manifest: Readonly<Record<string, unknown>>; }>>.

Awaited value: Page<{ path: string; manifest: Readonly<Record<string, unknown>>; }>.

Return value structure

Field	Type	Required	Description
items	{ path: string; manifest: Readonly<Record<string, unknown>>; }[]	Required	See the type definition and usage context.
status	string	Required	See the type definition and usage context.
cursor	string | undefined	Optional	See the type definition and usage context.
issues	{ code: string; }[]	Required	See the type definition and usage context.
issuesOmitted	number	Required	See the type definition and usage context.
coverage	{ exhausted: boolean; captureIncomplete?: boolean; }	Required	See the type definition and usage context.

readEvents

Read the events of one run.

ReflectionLogReader.readEvents(query: { run: string; sources?: readonly ("app" | "core" | "client")[]; types?: readonly string[]; cursor?: string; limit?: number; signal?: AbortSignal; }): Promise<Page<Record<string, unknown>>>

Read the events of one run.

Parameter	Type	Passing	Description
query	{ run: string; sources?: readonly ("app" | "core" | "client")[]; types?: readonly string[]; cursor?: string; limit?: number; signal?: AbortSignal; }	Required	—

Fields of query

Field	Type	Required	Description
run	string	Required	See the type definition and usage context.
sources	readonly ("app" | "core" | "client")[] | undefined	Optional	See the type definition and usage context.
types	readonly string[] | undefined	Optional	See the type definition and usage context.
cursor	string | undefined	Optional	See the type definition and usage context.
limit	number | undefined	Optional	See the type definition and usage context.
signal	AbortSignal | undefined	Optional	See the type definition and usage context.

Returns: Promise<Page<Record<string, unknown>>>.

Awaited value: Page<Record<string, unknown>>.

Return value structure

Field	Type	Required	Description
items	Record<string, unknown>[]	Required	See the type definition and usage context.
status	string	Required	See the type definition and usage context.
cursor	string | undefined	Optional	See the type definition and usage context.
issues	{ code: string; }[]	Required	See the type definition and usage context.
issuesOmitted	number	Required	See the type definition and usage context.
coverage	{ exhausted: boolean; captureIncomplete?: boolean; }	Required	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