SubFlowLogger

CORE · class · Runtime value

Full execution-owned recorder. Owns its store and may issue restricted delegates.

Import

TypeScript

import { SubFlowLogger } from '@jangts/agent-core/diagnostics';

JavaScript

import { SubFlowLogger } from '@jangts/agent-core/diagnostics';

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

Definition

class SubFlowLogger

Extends or implements: SubFlowLog.

Constructor

new SubFlowLogger(token: typeof loggerToken, store: Store): SubFlowLogger

Parameter	Type	Passing	Description
token	typeof loggerToken	Required	—
store	Store	Required	—

Fields of store

Field	Type	Required	Description
write	(input: ScopedSubFlowStepInput) => string | -1	Required	See the type definition and usage context.
fix	(stepId: string | -1, patch: SubFlowStepFix) => boolean	Required	See the type definition and usage context.
readAll	() => readonly Readonly<RecordedSubStep>[]	Required	Both logger classes return the same complete immutable ledger.
owns	(stepId: string | -1, subnodeId: string) => boolean	Required	See the type definition and usage context.
isActive	() => boolean	Required	See the type definition and usage context.
nextNativeSubnodeId	(kind: string, definitionId: string) => string	Required	See the type definition and usage context.
warn	(operation: "write" | "fix", reason: RejectionReason) => void	Required	See the type definition and usage context.

Returns: SubFlowLogger.

Member index

Member	Purpose
write	See the overload below for full inputs and outputs.
fix	See the overload below for full inputs and outputs.
readAll	See the overload below for full inputs and outputs.
fork	Issue a delegate for an App-owned logical group; no execution or scheduling is implied.

Member details

write

Instance method.

write(input: SubFlowStepInput): string | -1

Parameter	Type	Passing	Description
input	SubFlowStepInput	Required	—

Fields of input

Field	Type	Required	Description
kind	string | undefined	Optional	Read-only. Optional family classification; defaults to the custom type when omitted.
payload	Readonly<Record<string, SubFlowValue>> | undefined	Optional	Read-only. See the type definition and usage context.
subnodeId	string | undefined	Optional	Read-only. Logical subnode grouping within this node visit; independent of individual log ids.
type	string | undefined	Optional	Read-only. App-defined business log type; never a write/fix operation enum.
parentStepId	string | undefined	Optional	Read-only. Reported parent step, forming a tree; absent for a top-level step.
relatedDefinitionId	string | undefined	Optional	Read-only. Self-reported reference only; never a workflow dispatch identity.
relatedInvocationId	string | undefined	Optional	Read-only. Real model/tool invocation identity, kept separate from the node-local subnode id.
name	string	Required	Read-only. Short reported label.
status	"error" | "success" | "unknown" | "planned" | "running" | "cancelled" | "skipped" | undefined	Optional	Read-only. Reported lifecycle status; omission means the node did not report one.
usedModel	boolean | undefined	Optional	Read-only. This step's own reported model use, never a descendant rollup.
startedAtMs	number | undefined	Optional	Read-only. Reported start instant in epoch milliseconds.
endedAtMs	number | undefined	Optional	Read-only. Reported end instant in epoch milliseconds; only meaningful for terminal statuses.
nextStepIds	readonly string[] | undefined	Optional	Read-only. Reported successor step ids, for display only.
caseId	string | undefined	Optional	Read-only. Reported case or variant id, interpreted by the App.
summary	string | undefined	Optional	Read-only. Reported one-line summary.

Returns: string \| -1.

fix

Instance method.

fix(stepId: string | -1, patch: SubFlowStepFix): boolean

Parameter	Type	Passing	Description
stepId	string | -1	Required	—
patch	SubFlowStepFix	Required	—

Fields of patch

Field	Type	Required	Description
status	"error" | "success" | "unknown" | "planned" | "running" | "cancelled" | "skipped" | undefined	Optional	Read-only. See the type definition and usage context.
usedModel	boolean | undefined	Optional	Read-only. See the type definition and usage context.
startedAtMs	number | undefined	Optional	Read-only. See the type definition and usage context.
endedAtMs	number | undefined	Optional	Read-only. See the type definition and usage context.
summary	string | undefined	Optional	Read-only. See the type definition and usage context.
nextStepIds	readonly string[] | undefined	Optional	Read-only. See the type definition and usage context.
payload	Readonly<Record<string, SubFlowValue>> | undefined	Optional	Read-only. Fill missing result fields; existing facts cannot be replaced.

Returns: boolean.

readAll

Instance method.

readAll(): readonly Readonly<RecordedSubStep>[]

No call parameters.

Returns: readonly Readonly<RecordedSubStep>[].

fork

Instance method.

Issue a delegate for an App-owned logical group; no execution or scheduling is implied.

fork(subnodeId: string): ScopedSubFlowLogger

Issue a delegate for an App-owned logical group; no execution or scheduling is implied.

Parameter	Type	Passing	Description
subnodeId	string	Required	—

Returns: ScopedSubFlowLogger.

Examples

• Process observation and node reports: The App subscribes to Core execution facts; nodes report their own usedModel and use an instance sub-logger to record intent first and then results, while the Loop owns identity and logging.

Observe the nodes and model events a task passes through

Beginner · Node.js

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';

type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({
  id: 'greeting',
  nodes: [{
    id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
    run: state => ({ answer: '你好，' + state.name }),
    routes: [route.deliver('answer')],
  }],
});
const agent = new AgentCoreEngine({ workflow, execution: {
  observe: { event(event) { console.log(event.type, event.eventId); } },
} });
console.log(await agent.run({ name: 'Ivan' }));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({
    id: 'greeting',
    nodes: [{
            id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
            run: state => ({ answer: '你好，' + state.name }),
            routes: [route.deliver('answer')],
        }],
});
const agent = new AgentCoreEngine({ workflow, execution: {
        observe: { event(event) { console.log(event.type, event.eventId); } },
    } });
console.log(await agent.run({ name: 'Ivan' }));

Report a business stage while the node executes

Configuration · Node.js

The node only reports facts it knows; Core owns node identity and execution association.

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({ id: 'greeting', nodes: [{
  id: 'greet', description: '生成问候', startsRound: true,
  run(state, context) {
    context.report({ payload: { phase: 'formatting' } });
    return { answer: '你好，' + state.name };
  }, routes: [route.deliver('answer')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: {
  observe: { event(event) { console.log(event.type); } },
} });
console.log(await agent.run({ name: 'Ivan' }));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'greeting', nodes: [{
            id: 'greet', description: '生成问候', startsRound: true,
            run(state, context) {
                context.report({ payload: { phase: 'formatting' } });
                return { answer: '你好，' + state.name };
            }, routes: [route.deliver('answer')],
        }] });
const agent = new AgentCoreEngine({ workflow, execution: {
        observe: { event(event) { console.log(event.type); } },
    } });
console.log(await agent.run({ name: 'Ivan' }));

Record an async plan first, then fill in the result

Configuration · Node.js

A scoped logger binds the group and only fixes its own writes; readAll exposes the full ledger. Every fix appends an independent record linked to its original write, without logger submission.

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { result?: string };
const workflow = defineWorkflow<State, string>({ id: 'prepare', nodes: [{
  id: 'prepare', description: '准备资料', async run(_, context) {
    const subs = context.createSubFlowLogger();
    const read = subs.fork('material-read');
    const id = read.write({ name: '读取资料', kind: 'read', type: 'material.read' });
    read.fix(id, { status: 'running' });
    const result = await Promise.resolve('已准备');
    read.fix(id, { status: 'success', usedModel: false, payload: { result } });
    context.report({ usedModel: false });
    console.log(read.readAll());
    return { result };
  }, routes: [route.deliver('result')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: { observe: {
  accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
  event(event) { if (event.type === 'node.progress') console.log(event.payload.subStep, event.subSteps); },
} } });
console.log(await agent.run({}));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'prepare', nodes: [{
            id: 'prepare', description: '准备资料', async run(_, context) {
                const subs = context.createSubFlowLogger();
                const read = subs.fork('material-read');
                const id = read.write({ name: '读取资料', kind: 'read', type: 'material.read' });
                read.fix(id, { status: 'running' });
                const result = await Promise.resolve('已准备');
                read.fix(id, { status: 'success', usedModel: false, payload: { result } });
                context.report({ usedModel: false });
                console.log(read.readAll());
                return { result };
            }, routes: [route.deliver('result')],
        }] });
const agent = new AgentCoreEngine({ workflow, execution: { observe: {
            accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
            event(event) { if (event.type === 'node.progress')
                console.log(event.payload.subStep, event.subSteps); },
        } } });
console.log(await agent.run({}));

Related policy source

• Shared execution fact source and consumption isolation
• Sub-step statuses and their progression

Related definitions

• RecordedSubStep
• ScopedSubFlowLogger
• SubFlowLog
• SubFlowStepFix
• SubFlowStepInput