ReflectionEvidence

KIT · interface · Type contract

Explicit metadata projection, not an arbitrary original event/payload.

Import

TypeScript

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

JavaScript

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

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

Definition

interface ReflectionEvidence

Extends or implements: Partial< Pick<DiagnosticIdentity, (typeof reflectionIdentityFields)[number]> >.

Field structure

Field	Type	Required	Description
id	string	Required	Read-only. Evidence id cited by findings when they rely on this item.
runId	string	Required	Read-only. Run the item belongs to; queries are scoped by run.
type	string	Required	Read-only. Evidence type, matched against ReflectionQuery.types.
occurredAtMs	number | undefined	Optional	Read-only. See the type definition and usage context.
sequence	number | undefined	Optional	Read-only. Ordering key inside the source; ascending.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
status	string | undefined	Optional	Read-only. See the type definition and usage context.
code	string | undefined	Optional	Read-only. Error or protocol code recorded on the item.
calls	number | undefined	Optional	Read-only. Model or tool calls represented by the item.
durationMs	number | undefined	Optional	Read-only. See the type definition and usage context.
inputChars	number | undefined	Optional	Read-only. See the type definition and usage context.
outputChars	number | undefined	Optional	Read-only. See the type definition and usage context.
expiresAtMs	number | undefined	Optional	Read-only. Instant after which the item is no longer retained by the source.
spanId	string | undefined	Optional	Read-only. Span that produced the fact.
parentSpanId	string | undefined	Optional	Read-only. Enclosing span; absent for a root span.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation, when one invocation triggers another.
invocationId	string | undefined	Optional	Read-only. Invocation that produced the fact, when the fact belongs to one.
nodeRole	"invocation" | "workflow-node" | "workflow-boundary" | "loop-step" | undefined	Optional	Read-only. Role the emitting span plays in the execution graph.
agentId	string | undefined	Optional	Read-only. App-owned agent identity.
branchId	string | undefined	Optional	Read-only. App-owned branch identity.
agentVersionId	string | undefined	Optional	Read-only. App-owned immutable version identity of the agent definition.
parentBranchId	string | undefined	Optional	Read-only. Branch this branch was forked from, when applicable.
parentAgentVersionId	string | undefined	Optional	Read-only. Version of the parent branch at the fork point.
forkPointId	string | undefined	Optional	Read-only. App-owned fork marker shared by the forked branch and its origin.
workflowInvocationId	string | undefined	Optional	Read-only. Workflow invocation the fact belongs to.
workflowNodeId	string | undefined	Optional	Read-only. Workflow node invocation the fact belongs to.
definitionId	string | undefined	Optional	Read-only. Id of that definition.

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

• DiagnosticIdentity
• reflectionIdentityFields