ContextRecord

CORE · type · Type contract

One journal entry: a model call, a tool request or a tool result.

The three variants are distinguished by type; value/input stay unknown because their domain meaning belongs to the App.

Import

TypeScript

import type { ContextRecord } from '@jangts/agent-core/context';

JavaScript

/** @typedef {import('@jangts/agent-core/context').ContextRecord} ContextRecord */

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/context, @jangts/agent-core/journal.

Definition

Type: ContextRecord

Type expression

type ContextRecord = RecordIdentity &
  /** A model call was made for `stageId`; `value` is what the call produced. */
  (
    | { readonly type: 'model'; readonly stageId: string; readonly value: unknown }
    /** A tool call was requested; `input` is the raw request payload. */
    | { readonly type: 'tool'; readonly toolId: string; readonly input: unknown }
    /** A tool call settled; `value` carries the result or the failure detail. */
    | {
        readonly type: 'tool-result';
        readonly toolId: string;
        readonly status: 'success' | 'error' | 'cancelled';
        readonly value: unknown;
      }
  );

Union branch structure

Optional shapes of ContextRecord: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
runId	string | undefined	Optional	Read-only. Root run this invocation belongs to, when the host runs inside a diagnostics scope.
spanId	string | undefined	Optional	Read-only. Diagnostics span of this invocation.
parentSpanId	string | undefined	Optional	Read-only. Span that caused this invocation; absent for a root invocation.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation when one call triggers another.
invocationId	string	Required	Read-only. Opaque per-invocation id shared by receipt, events and diagnostic records. Invocation that produced the record.
startedAtMs	number	Required	Read-only. Start instant in epoch milliseconds.
durationMs	number	Required	Read-only. Elapsed milliseconds from start to completion.
producerSequence	number	Required	Read-only. Monotonic order within this journal; starts at 1 and never repeats.
occurredAtMs	number	Required	Read-only. Instant the record was written, in epoch milliseconds.
type	"model"	Required	Read-only. See the type definition and usage context.
stageId	string	Required	Read-only. See the type definition and usage context.
value	unknown	Required	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
runId	string | undefined	Optional	Read-only. Root run this invocation belongs to, when the host runs inside a diagnostics scope.
spanId	string | undefined	Optional	Read-only. Diagnostics span of this invocation.
parentSpanId	string | undefined	Optional	Read-only. Span that caused this invocation; absent for a root invocation.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation when one call triggers another.
invocationId	string	Required	Read-only. Opaque per-invocation id shared by receipt, events and diagnostic records. Invocation that produced the record.
startedAtMs	number	Required	Read-only. Start instant in epoch milliseconds.
durationMs	number	Required	Read-only. Elapsed milliseconds from start to completion.
producerSequence	number	Required	Read-only. Monotonic order within this journal; starts at 1 and never repeats.
occurredAtMs	number	Required	Read-only. Instant the record was written, in epoch milliseconds.
type	"tool"	Required	Read-only. See the type definition and usage context.
toolId	string	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. See the type definition and usage context.

Branch 3

Field	Type	Required	Description
runId	string | undefined	Optional	Read-only. Root run this invocation belongs to, when the host runs inside a diagnostics scope.
spanId	string | undefined	Optional	Read-only. Diagnostics span of this invocation.
parentSpanId	string | undefined	Optional	Read-only. Span that caused this invocation; absent for a root invocation.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation when one call triggers another.
invocationId	string	Required	Read-only. Opaque per-invocation id shared by receipt, events and diagnostic records. Invocation that produced the record.
startedAtMs	number	Required	Read-only. Start instant in epoch milliseconds.
durationMs	number	Required	Read-only. Elapsed milliseconds from start to completion.
producerSequence	number	Required	Read-only. Monotonic order within this journal; starts at 1 and never repeats.
occurredAtMs	number	Required	Read-only. Instant the record was written, in epoch milliseconds.
type	"tool-result"	Required	Read-only. See the type definition and usage context.
toolId	string	Required	Read-only. See the type definition and usage context.
status	"error" | "success" | "cancelled"	Required	Read-only. See the type definition and usage context.
value	unknown	Required	Read-only. See the type definition and usage context.

Examples

• ContextJournal: the in-request projection of receipts: Turn real call receipts into in-request records usable in later context, without starting another persistent logging system.

Read the model receipt already recorded by the Runner

Beginner · Node.js

TypeScript

import { ModelRunner } from '@jangts/agent-core';
const runner = new ModelRunner({ provider: { async *stream() { yield '服务运行正常'; } } });
const result = await runner.invoke('查询服务状态');
console.log(result.invocation.invocationId);
console.log(runner.journal.snapshot());

JavaScript

import { ModelRunner } from '@jangts/agent-core';
const runner = new ModelRunner({ provider: { async *stream() { yield '服务运行正常'; } } });
const result = await runner.invoke('查询服务状态');
console.log(result.invocation.invocationId);
console.log(runner.journal.snapshot());

An App adapter records the local tool it actually executes

Configuration · Node.js

TypeScript

import { ContextJournal } from '@jangts/agent-core/journal';
const journal = new ContextJournal();
const invocationId = journal.beginTool({ toolId: 'get_status', input: {} });
// 此处由 App 实际执行本地读取；不是模型提供的回执。
const status = '服务运行正常';
journal.finishTool({ invocationId, status: 'success', value: status });
console.log(journal.snapshot());

JavaScript

import { ContextJournal } from '@jangts/agent-core/journal';
const journal = new ContextJournal();
const invocationId = journal.beginTool({ toolId: 'get_status', input: {} });
// 此处由 App 实际执行本地读取；不是模型提供的回执。
const status = '服务运行正常';
journal.finishTool({ invocationId, status: 'success', value: status });
console.log(journal.snapshot());

Related definitions

• InvocationMetadata