@jangts/agent-core 0.2.5 → 0.3.6

package/dist/esm/structs/execution/workflow.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowChainSource } from './workflow-views.js';
 /**
  * Workflow contract: a state graph whose nodes report their own use of model and tools.
  *
@@ -66,8 +67,6 @@ export interface WorkflowNodeReport {
     readonly usedModel?: boolean;
     /** App-defined progress detail; collected only when content logging is enabled. */
     readonly payload?: unknown;
-    /** Logger owned by this visit, used to report sub-steps. */
-    readonly subs?: import('../debug.js').SubFlowLogger;
 }
 /** One node of the graph. */
 export type WorkflowNode<State, Result, Runtime = undefined> = {
@@ -94,7 +93,7 @@ export type WorkflowNode<State, Result, Runtime = undefined> = {
     readonly requires?: readonly (keyof State & string)[];
     /** State keys this node is expected to produce; validated after `run`. */
     readonly provides?: readonly (keyof State & string)[];
-    /** Candidate successors, evaluated in order. */
+    /** Candidate successors, evaluated in order. A getter must be pure; registration reads it once. */
     readonly routes: readonly WorkflowRoute<State, Result, Runtime>[];
     /** Return only changed fields. Core commits them after cancellation and output checks. */
     readonly run?: (state: Readonly<State>, context: WorkflowContext<Runtime>) => void | Partial<State> | Promise<void | Partial<State>>;
@@ -103,6 +102,8 @@ export type WorkflowNode<State, Result, Runtime = undefined> = {
 export type AgentWorkflowDefinition<State, Result, Runtime = undefined> = {
     /** Stable workflow id, also reported in every event. */
     readonly id: string;
+    /** App-owned authorized diagnostic reader; no global run storage is installed. */
+    readonly chainSource?: WorkflowChainSource;
     /** Definition revision; lets hosts distinguish executions of different graph versions. */
     readonly revision?: string;
     readonly nodes: readonly WorkflowNode<State, Result, Runtime>[];

package/dist/esm/structs/index.d.ts

@@ -55,3 +55,4 @@ export type * from './invocation.js';
 export type * from './debug.js';
 export type * from './execution/events.js';
 export type * from './execution/cache.js';
+export type * from './execution/workflow-views.js';

package/dist/esm/structs/model/runtime.d.ts

@@ -175,6 +175,8 @@ export type ModelRunnerOptions<Transports extends readonly ModelTransportDefinit
 } & ModelRunnerSettings;
 /** One model call request. The input shape selects prompt mode or message mode. */
 export type ModelCallRequest<Transport = string> = {
+    /** Record this call in the supplied logger; omission adds no sub-flow record. */
+    readonly logger?: import('../debug.js').SubFlowLogger;
     /** Additional cancellation can shorten, never replace, the Runner lifetime. */
     readonly signal?: AbortSignal;
     /** Parent observation scope for this invocation; never changes execution budget or signal. */

package/dist/esm/support/context/nodes.js

@@ -9,6 +9,7 @@
  * Main exports: `createContextProcessingNode`, `createContextSelectionNode`,
  * `createContextReductionNode` and their result/definition types.
  */
+import { nativeSubFlowAsync } from '../../diagnostics/native-sub-flow.js';
 import { beginContextProcessing, finishContextProcessing, chooseSteps, applyReduction, needsReduction, watermarks, validateReductionTargets, contextPolicyCatalog, validateContextPolicy, } from './processing.js';
 import { modelRunnerDefaults } from '../../model/defaults.js';
 import { synchronous } from '../../utils/synchronous.js';
@@ -124,53 +125,55 @@ function contextNode(definition, execute) {
         onErrorRouteId: definition.onErrorRouteId,
         routes: definition.routes,
         async run(state, context) {
-            // The node timeout is an additional bound; parent cancellation still wins.
-            const signal = combineSignals(context.signal, AbortSignal.timeout(timeoutMs));
-            const prepared = selectPrepared
-                ? selectPrepared(state, context)
-                : context.model.prepare(typeof request === 'function' ? request(state, context) : request);
-            const input = synchronous(plan(state, context), 'Context plans must be synchronous');
-            // An empty measurement reports the allowance left after transport, instruction and schema
-            // overhead, so processing must fit inside whichever limit is tighter.
-            const overhead = prepared.measure([]);
-            const fullLimit = Math.min(input.maxInputChars, overhead.maxInputChars);
-            const bodyLimit = fullLimit;
-            breakWhile(bodyLimit < 1, 'No input capacity for context');
-            const work = beginContextProcessing({
-                fragments: input.fragments,
-                additionalMessages: input.additionalMessages,
-                originalFragments: input.originalFragments,
-                mutableFragmentIds: input.mutableFragmentIds,
-                maxInputChars: bodyLimit,
-            }, policy, {
-                stageId: prepared.stageId,
-                signal,
-                diagnostics: context.diagnostics,
-                compressors,
-                selectors,
-                // Read lazily so handlers see the live budget rather than the value at preparation.
-                remainingCalls: () => prepared.remainingCalls,
-                callModel: (options) => context.model.invoke({
-                    ...options,
-                    modelId: options.modelId ?? prepared.modelId,
+            return nativeSubFlowAsync(context, 'context', definition.id, async () => {
+                // The node timeout is an additional bound; parent cancellation still wins.
+                const signal = combineSignals(context.signal, AbortSignal.timeout(timeoutMs));
+                const prepared = selectPrepared
+                    ? selectPrepared(state, context)
+                    : context.model.prepare(typeof request === 'function' ? request(state, context) : request);
+                const input = synchronous(plan(state, context), 'Context plans must be synchronous');
+                // An empty measurement reports the allowance left after transport, instruction and schema
+                // overhead, so processing must fit inside whichever limit is tighter.
+                const overhead = prepared.measure([]);
+                const fullLimit = Math.min(input.maxInputChars, overhead.maxInputChars);
+                const bodyLimit = fullLimit;
+                breakWhile(bodyLimit < 1, 'No input capacity for context');
+                const work = beginContextProcessing({
+                    fragments: input.fragments,
+                    additionalMessages: input.additionalMessages,
+                    originalFragments: input.originalFragments,
+                    mutableFragmentIds: input.mutableFragmentIds,
+                    maxInputChars: bodyLimit,
+                }, policy, {
+                    stageId: prepared.stageId,
                     signal,
-                }),
-                ...(overhead.counterId
-                    ? {
-                        tokenBudget: {
-                            counterId: overhead.counterId,
-                            inputLimit: overhead.inputTokenLimit,
-                            measure: (messages) => prepared.measure(messages).inputTokens,
-                        },
-                    }
-                    : {}),
+                    diagnostics: context.diagnostics,
+                    compressors,
+                    selectors,
+                    // Read lazily so handlers see the live budget rather than the value at preparation.
+                    remainingCalls: () => prepared.remainingCalls,
+                    callModel: (options) => context.model.invoke({
+                        ...options,
+                        modelId: options.modelId ?? prepared.modelId,
+                        signal,
+                    }),
+                    ...(overhead.counterId
+                        ? {
+                            tokenBudget: {
+                                counterId: overhead.counterId,
+                                inputLimit: overhead.inputTokenLimit,
+                                measure: (messages) => prepared.measure(messages).inputTokens,
+                            },
+                        }
+                        : {}),
+                });
+                context.report({ payload: { phase: 'processing', fragmentCount: input.fragments.length } });
+                const result = await execute(work, prepared, fullLimit, state, context);
+                // Never report or commit a result produced after cancellation.
+                signal.throwIfAborted();
+                context.report({ payload: { phase: 'processed', report: work.report } });
+                return synchronous(update(result, state), 'Context node updates must be synchronous');
             });
-            context.report({ payload: { phase: 'processing', fragmentCount: input.fragments.length } });
-            const result = await execute(work, prepared, fullLimit, state, context);
-            // Never report or commit a result produced after cancellation.
-            signal.throwIfAborted();
-            context.report({ payload: { phase: 'processed', report: work.report } });
-            return synchronous(update(result, state), 'Context node updates must be synchronous');
         },
     };
 }

package/dist/esm/support/context/processing.js

@@ -11,6 +11,7 @@
  * `finishContextProcessing` (staged runs), the policy/reduction catalogs and the individual
  * validation, measurement and reduction helpers used by workflow nodes.
  */
+import { nativeSubFlowAsync } from '../../diagnostics/native-sub-flow.js';
 import { snapshotFragment, snapshotMessage } from './snapshot.js';
 import { auditContextChange as audit } from '../../context/audit.js';
 import { historyGroups, validateRecentHistory } from './history.js';
@@ -595,7 +596,9 @@ export function finishContextProcessing(state) {
  * @throws {BudgetError} When a handler exhausts its call allowance.
  */
 export async function processContext(plan, policy, ports) {
-    const state = beginContextProcessing(plan, policy, ports);
-    await contextPolicyCatalog[policy.mode].run(state);
-    return finishContextProcessing(state);
+    return nativeSubFlowAsync(ports, 'context', policy.mode, async () => {
+        const state = beginContextProcessing(plan, policy, ports);
+        await contextPolicyCatalog[policy.mode].run(state);
+        return finishContextProcessing(state);
+    });
 }

package/dist/esm/support/decorators/definition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal decoration: construct definition classes or bind methods to their real host,
+ * compile through existing entry points and automatically register in the kind's root.
+ */
+import { type DefinitionKind, type IdentifiedDefinition } from './pool.js';
+type Handler = (this: any, ...args: any[]) => any;
+/** Preserve union branches when removing the decorator-owned id. */
+export type DefinitionBody<Definition> = Definition extends unknown ? Omit<Definition, 'id'> : never;
+/** Namespaces group external registration without changing Core options. */
+export interface DecorationOptions {
+    readonly ns?: string | readonly string[];
+}
+export type ClassDecoration<Definition extends IdentifiedDefinition> = <Constructor extends new () => DefinitionBody<Definition>>(target: Constructor, context: ClassDecoratorContext<Constructor>) => void;
+export type MethodDecoration<Method extends Handler> = <This>(method: (this: This, ...args: Parameters<Method>) => ReturnType<Method>, context: ClassMethodDecoratorContext<This, (this: This, ...args: Parameters<Method>) => ReturnType<Method>>) => void;
+/** Class definitions register once after static initialization and successful construction. */
+export declare function classDecoration<Definition extends IdentifiedDefinition>(kind: DefinitionKind, id: string, options: DecorationOptions, compile: (value: Definition) => Definition): ClassDecoration<Definition>;
+/** Method initializers bind and register automatically; no scanning or caller-side bind is needed. */
+export declare function methodDecoration<Definition extends IdentifiedDefinition, Method extends Handler>(kind: DefinitionKind, id: string, metadata: DefinitionBody<Definition>, handlerKey: keyof Definition, options: DecorationOptions, compile: (value: Definition) => Definition): MethodDecoration<Method>;
+export {};

package/dist/esm/support/decorators/definition.js

@@ -0,0 +1,38 @@
+/**
+ * Internal decoration: construct definition classes or bind methods to their real host,
+ * compile through existing entry points and automatically register in the kind's root.
+ */
+import { registerDefinition } from './pool.js';
+/** Restore only the decorator-owned id, preserving instance identity, getters and private state. */
+function withId(id, instance) {
+    if ('id' in instance)
+        throw new TypeError('Decoration supplies id; do not also define it on the class');
+    Object.defineProperty(instance, 'id', { value: id, enumerable: true });
+    return instance;
+}
+/** Class definitions register once after static initialization and successful construction. */
+export function classDecoration(kind, id, options, compile) {
+    return (_target, context) => {
+        if (context?.kind !== 'class')
+            throw new TypeError('Use standard class decorator semantics');
+        context.addInitializer(function () {
+            registerDefinition(kind, compile(withId(id, new this())), options.ns);
+        });
+    };
+}
+/** Method initializers bind and register automatically; no scanning or caller-side bind is needed. */
+export function methodDecoration(kind, id, metadata, handlerKey, options, compile) {
+    return (method, context) => {
+        if (context?.kind !== 'method' || context.static || context.private)
+            throw new TypeError('Use a standard public instance method decorator');
+        context.addInitializer(function () {
+            const value = { ...metadata, [handlerKey]: method.bind(this) };
+            for (const key of Reflect.ownKeys(value)) {
+                const member = value[key];
+                if (typeof member === 'function')
+                    value[key] = member.bind(this);
+            }
+            registerDefinition(kind, compile(withId(id, value)), options.ns);
+        });
+    };
+}

package/dist/esm/support/decorators/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Optional standard decorators. Classes are definition implementations; public instance methods
+ * keep their original host. Only definitions are created here, never Engines or ModelRunners.
+ */
+import type { WorkflowNode, AgentWorkflowDefinition } from '../../structs/execution/workflow.js';
+import type { AgentCoreEngineSetup } from '../../execution/engine.js';
+import type { ToolDefinition } from '../../structs/capabilities/tools.js';
+import type { ContextFragmentConfig } from '../../structs/support/context.js';
+import type { ModelRunnerOptions } from '../../structs/model/runtime.js';
+import { type ClassDecoration, type MethodDecoration, type DecorationOptions } from './definition.js';
+import type { IdentifiedDefinition } from './pool.js';
+export { nodePool, toolPool, fragmentPool, workflowPool, agentPool, modelPool } from './pool.js';
+export type { IdentifiedDefinition, DefinitionReader } from './pool.js';
+export type { ClassDecoration, MethodDecoration, DecorationOptions } from './definition.js';
+export type { Node, Tool, Fragment, Workflow, Agent, Model } from './types.js';
+/** Method metadata describes the adapted handler, with optional external namespaces. */
+type MethodOptions<Definition extends IdentifiedDefinition, Key extends keyof Definition> = Omit<Definition, 'id' | Key> & DecorationOptions;
+/** Instantiate a node definition class once, injecting its id; graph validation stays in Workflow. */
+export declare function node<State = any, Result = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<WorkflowNode<State, Result, App>>;
+/** Bind a named host method as run without renaming or manually binding the original object. */
+export declare function node<State = any, Result = unknown, App = any>(id: string, options: MethodOptions<WorkflowNode<State, Result, App>, 'run'>): MethodDecoration<NonNullable<WorkflowNode<State, Result, App>['run']>>;
+/** Instantiate a tool definition class; schema and authorization stay with existing defineTool. */
+export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<ToolDefinition<Input, Output, App>>;
+/** Bind an existing host method as the tool's execute callback. */
+export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options: MethodOptions<ToolDefinition<Input, Output, App>, 'execute'>): MethodDecoration<ToolDefinition<Input, Output, App>['execute']>;
+/** Instantiate a self-describing fragment class; the original builder owns formatting checks. */
+export declare function fragment<Input = unknown>(id: string, options?: DecorationOptions): ClassDecoration<ContextFragmentConfig<Input>>;
+/** Bind a host's formatter method into an original fragment configuration. */
+export declare function fragment<Input = unknown>(id: string, options: MethodOptions<ContextFragmentConfig<Input>, 'format'>): MethodDecoration<ContextFragmentConfig<Input>['format']>;
+/** Instantiate and validate workflow options, leaving actual execution with the original Engine. */
+export declare function workflow<State = any, Result = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<AgentWorkflowDefinition<State, Result, App>>;
+/** Agent id is an external pool identity, not an override of Core branch or request identity. */
+export type AgentOptions<State = unknown, Result = unknown, App = undefined> = AgentCoreEngineSetup<State, Result, App> & IdentifiedDefinition;
+/** Instantiate an Engine configuration class without creating an Engine, budget or request. */
+export declare function agent<State = unknown, Result = unknown, App = undefined>(id: string, options?: DecorationOptions): ClassDecoration<AgentOptions<State, Result, App>>;
+/** Model id is only a pool key; Core still owns the configured model/transport identities. */
+export type ModelOptions = ModelRunnerOptions & IdentifiedDefinition;
+/** Instantiate and validate model options without creating a Runner or consuming calls. */
+export declare function model(id: string, options?: DecorationOptions): ClassDecoration<ModelOptions>;

package/dist/esm/support/decorators/index.js

@@ -0,0 +1,48 @@
+import { defineTool } from '../tools.js';
+import { defineWorkflow } from '../../execution/workflow.js';
+import { defineContextFragments } from '../context/assembly.js';
+import { snapshotModelBinding } from '../../model/binding.js';
+import { classDecoration, methodDecoration, } from './definition.js';
+export { nodePool, toolPool, fragmentPool, workflowPool, agentPool, modelPool } from './pool.js';
+/** Internal conversion shared by node/tool/fragment; never a public free-function adapter. */
+function decorate(kind, id, options, key, compile) {
+    return (value, context) => {
+        if (context?.kind === 'class') {
+            classDecoration(kind, id, options, compile)(value, context);
+        }
+        else {
+            const { ns, ...metadata } = options;
+            methodDecoration(kind, id, metadata, key, { ns }, compile)(value, context);
+        }
+    };
+}
+export function node(id, options = {}) {
+    return decorate('node', id, options, 'run', (value) => value);
+}
+export function tool(id, options = {}) {
+    return decorate('tool', id, options, 'execute', (value) => defineTool(value));
+}
+export function fragment(id, options = {}) {
+    return decorate('fragment', id, options, 'format', (value) => {
+        defineContextFragments([value]);
+        return value;
+    });
+}
+/** Instantiate and validate workflow options, leaving actual execution with the original Engine. */
+export function workflow(id, options = {}) {
+    return classDecoration('workflow', id, options, (value) => {
+        defineWorkflow(value);
+        return value;
+    });
+}
+/** Instantiate an Engine configuration class without creating an Engine, budget or request. */
+export function agent(id, options = {}) {
+    return classDecoration('agent', id, options, (value) => value);
+}
+/** Instantiate and validate model options without creating a Runner or consuming calls. */
+export function model(id, options = {}) {
+    return classDecoration('model', id, options, (value) => {
+        snapshotModelBinding(value);
+        return value;
+    });
+}

package/dist/esm/support/decorators/pool.d.ts

@@ -0,0 +1,97 @@
+import type { WorkflowNode, AgentWorkflowDefinition } from '../../structs/execution/workflow.js';
+import type { ToolDefinition } from '../../structs/capabilities/tools.js';
+import type { ContextFragmentConfig } from '../../structs/support/context.js';
+/** Registration identity; ids are unique within one kind and namespace. */
+export interface IdentifiedDefinition {
+    readonly id: string;
+}
+/** Read-only roots. A typed read describes the expected contract, not a static id/type lookup. */
+export interface DefinitionReader<Definition extends IdentifiedDefinition> {
+    get<Value extends Definition = Definition>(id: string, ns?: string): Value | undefined;
+    getAll<Value extends Definition = Definition>(ns?: string): readonly Value[];
+    pick<Value extends Definition = Definition>(ids: readonly string[], ns?: string): readonly Value[];
+}
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+export declare const definitionKinds: readonly ["node", "tool", "fragment", "workflow", "agent", "model"];
+export type DefinitionKind = (typeof definitionKinds)[number];
+/** Preflight every destination so a conflict never leaves partial multi-namespace registration. */
+export declare function registerDefinition(kind: DefinitionKind, definition: IdentifiedDefinition, ns?: string | readonly string[]): void;
+/** Decorated nodes; ids are unique within each namespace. */
+export declare const nodePool: DefinitionReader<WorkflowNode<any, any, any>>;
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+export declare const toolPool: DefinitionReader<ToolDefinition<any, any, any, string>>;
+/** Decorated fragment configurations; use the original builder to assemble them. */
+export declare const fragmentPool: DefinitionReader<ContextFragmentConfig<any>>;
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+export declare const workflowPool: DefinitionReader<AgentWorkflowDefinition<any, any, any>>;
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+export declare const agentPool: DefinitionReader<(Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: import("../../index.js").AgentModelBinding;
+    models?: never;
+} & {
+    workflow?: undefined;
+    app?: never;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition) | (Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: string;
+    models: Readonly<Record<string, import("../../index.js").AgentModelBinding>>;
+    maxModelCalls?: number;
+} & {
+    workflow?: undefined;
+    app?: never;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition) | (Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: import("../../index.js").AgentModelBinding;
+    models?: never;
+} & {
+    readonly workflow: import("../../index.js").AgentWorkflow<any, any, any>;
+} & {
+    readonly app?: undefined;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition) | (Omit<import("../../index.js").AgentCoreEngineOptions & {
+    readonly branch?: import("../../index.js").AgentBranch;
+    readonly tools?: {
+        invoke: (request: import("../../index.js").ToolInvocationRequest) => Promise<import("../../index.js").ToolResult<unknown>>;
+    } | Pick<import("../../index.js").ToolRegistry<import("../../index.js").ExecutableTool>, "invokeAsync">;
+} & {
+    model?: string;
+    models: Readonly<Record<string, import("../../index.js").AgentModelBinding>>;
+    maxModelCalls?: number;
+} & {
+    readonly workflow: import("../../index.js").AgentWorkflow<any, any, any>;
+} & {
+    readonly app?: undefined;
+}, "app"> & {
+    readonly app?: unknown;
+} & IdentifiedDefinition)>;
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+export declare const modelPool: DefinitionReader<{
+    provider: import("../../index.js").ChatProvider;
+    execution?: import("../../index.js").ExecutionOptions;
+    transports?: readonly import("../../index.js").ModelTransportDefinition<unknown>[] | undefined;
+    sink?: {
+        output?: import("../../index.js").ModelRunnerPorts["onOutput"];
+    };
+    errors?: {
+        inputBudget?: import("../../index.js").ModelRunnerPorts["inputBudgetError"];
+        outputBudget?: import("../../index.js").ModelRunnerPorts["outputBudgetError"];
+    };
+} & import("../../index.js").ModelRunnerSettings & IdentifiedDefinition>;

package/dist/esm/support/decorators/pool.js

@@ -0,0 +1,83 @@
+/**
+ * One process-realm definition registry per kind. The shared symbol makes ESM/CJS copies
+ * consume the same stores; consumers receive frozen read-only views, never pool factories.
+ */
+import { ProtocolRegistry } from '../../utils/protocol-registry.js';
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+export const definitionKinds = ['node', 'tool', 'fragment', 'workflow', 'agent', 'model'];
+const sharedKey = Symbol.for('@jangts/agent-core/decorator-roots/v2');
+const realm = globalThis;
+/** Allocate once per realm, including when another module format initialized the roots first. */
+function sharedPools() {
+    const existing = realm[sharedKey];
+    if (existing) {
+        if (existing.version !== 2 || definitionKinds.some((kind) => !existing.stores[kind]))
+            throw new TypeError('Incompatible decorator root registry');
+        return existing;
+    }
+    const stores = Object.fromEntries(definitionKinds.map((kind) => [kind, new Map()]));
+    const pools = Object.freeze({ version: 2, stores: Object.freeze(stores) });
+    Object.defineProperty(globalThis, sharedKey, { value: pools });
+    return pools;
+}
+/** Namespace is an exact, nonblank key; no trimming, fallback or hierarchy is applied. */
+function namespace(value) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError('Decorator namespace must be a nonempty string');
+    return value;
+}
+/** Preflight every destination so a conflict never leaves partial multi-namespace registration. */
+export function registerDefinition(kind, definition, ns = 'default') {
+    if (typeof definition.id !== 'string' || !definition.id.trim())
+        throw new TypeError('Invalid decorator definition id');
+    const requested = typeof ns === 'string' ? [ns] : ns;
+    if (!Array.isArray(requested) || requested.length === 0)
+        throw new TypeError('Decorator ns must be a namespace or a nonempty namespace array');
+    const names = [...new Set(requested.map(namespace))];
+    const store = sharedPools().stores[kind];
+    for (const name of names) {
+        if (store.get(name)?.has(definition.id))
+            throw new Error(`Duplicate ${kind} definition: ${definition.id} (ns: ${name})`);
+    }
+    for (const name of names) {
+        let entries = store.get(name);
+        if (!entries)
+            store.set(name, (entries = new ProtocolRegistry()));
+        entries.set(definition.id, definition);
+    }
+}
+/** Root reads never instantiate or execute definitions; array results are immutable snapshots. */
+function reader(kind) {
+    const store = sharedPools().stores[kind];
+    return Object.freeze({
+        get(id, ns = 'default') {
+            return store.get(namespace(ns))?.get(id);
+        },
+        getAll(ns = 'default') {
+            return Object.freeze([...(store.get(namespace(ns))?.values() ?? [])]);
+        },
+        pick(ids, ns = 'default') {
+            const entries = store.get(namespace(ns));
+            const selected = new ProtocolRegistry();
+            for (const id of ids) {
+                const definition = entries?.get(id);
+                if (!definition)
+                    throw new TypeError(`Unknown ${kind} definition: ${id} (ns: ${ns})`);
+                selected.set(id, definition);
+            }
+            return Object.freeze([...selected.values()]);
+        },
+    });
+}
+/** Decorated nodes; ids are unique within each namespace. */
+export const nodePool = reader('node');
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+export const toolPool = reader('tool');
+/** Decorated fragment configurations; use the original builder to assemble them. */
+export const fragmentPool = reader('fragment');
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+export const workflowPool = reader('workflow');
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+export const agentPool = reader('agent');
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+export const modelPool = reader('model');

package/dist/esm/support/decorators/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Class implementation contracts for definition decorators. The decorator supplies id;
+ * classes implement these named contracts instead of repeating Omit at every use site.
+ */
+import type { WorkflowNode, AgentWorkflowDefinition } from '../../structs/execution/workflow.js';
+import type { ToolDefinition } from '../../structs/capabilities/tools.js';
+import type { ContextFragmentConfig } from '../../structs/support/context.js';
+import type { AgentCoreEngineSetup } from '../../execution/engine.js';
+import type { ModelRunnerOptions } from '../../structs/model/runtime.js';
+import type { DefinitionBody } from './definition.js';
+/** A node implementation; its public id is supplied by @node. */
+export type Node<State, Result, App = undefined> = DefinitionBody<WorkflowNode<State, Result, App>>;
+/** A tool implementation with the original schema, authorization and execution contracts. */
+export type Tool<Input = unknown, Output = unknown, App = unknown> = DefinitionBody<ToolDefinition<Input, Output, App>>;
+/** A formatter and its original provenance, trust and budget configuration. */
+export type Fragment<Input = unknown> = DefinitionBody<ContextFragmentConfig<Input>>;
+/** A complete graph definition whose workflow id is supplied by @workflow. */
+export type Workflow<State, Result, App = undefined> = DefinitionBody<AgentWorkflowDefinition<State, Result, App>>;
+/** Original Engine configuration; union branches retain their required App/model relationships. */
+export type Agent<State = unknown, Result = unknown, App = undefined> = AgentCoreEngineSetup<State, Result, App>;
+/** Original Runner configuration; the decorator's pool id is not a model identity override. */
+export type Model = ModelRunnerOptions;

package/dist/esm/support/decorators/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils/invocation.d.ts

@@ -38,6 +38,7 @@ export declare function invocationResult<Value, Metadata extends InvocationMetad
  * @throws TypeError When the arity or the request shape is invalid.
  */
 export declare function toolInvocation(request: import('../structs/capabilities/tools.js').ToolInvocationRequest, arity: number): {
+    logger: import("../index.js").SubFlowLogger | undefined;
     toolId: string;
     input: unknown;
     diagnostics: import("../index.js").DiagnosticContext | undefined;

package/dist/esm/utils/invocation.js

@@ -41,6 +41,7 @@ export function toolInvocation(request, arity) {
         throw new TypeError('Use one tool request with toolId and input');
     }
     return {
+        logger: request.logger,
         toolId: request.toolId,
         input: request.input,
         diagnostics: request.diagnostics,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jangts/agent-core",
-  "version": "0.2.5",
+  "version": "0.3.6",
   "type": "commonjs",
   "license": "Apache-2.0",
   "description": "Platform-independent agent runtime and configurable modules for evidence, delivery, policies and interactions",
@@ -241,6 +241,11 @@
       "types": "./dist/esm/mock/web.d.ts",
       "import": "./dist/esm/mock/web.js",
       "require": "./dist/cjs/mock/web.js"
+    },
+    "./support/decorators": {
+      "types": "./dist/esm/support/decorators/index.d.ts",
+      "import": "./dist/esm/support/decorators/index.js",
+      "require": "./dist/cjs/support/decorators/index.js"
     }
   },
   "scripts": {
@@ -254,7 +259,8 @@
     "minisearch": "^7.2.0"
   },
   "devDependencies": {
-    "typescript": "~6.0.2"
+    "typescript": "~6.0.2",
+    "esbuild": "0.28.2"
   },
   "keywords": [
     "ai",
@@ -271,6 +277,8 @@
     "openai-compatible",
     "context-management",
     "streaming",
+    "decorators",
+    "typescript-decorators",
     "typescript",
     "nodejs",
     "browser"

package/dist/cjs/utils/debug.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.captureSubSteps = captureSubSteps;
-const sub_flow_js_1 = require("../diagnostics/sub-flow.js");
-const synchronous_js_1 = require("./synchronous.js");
-/**
- * Read the current sub-step log of one execution visit.
- *
- * A missing reader or a logger that yields nothing produces the empty shape, which
- * lets callers spread the result unconditionally. Failures are reported as one
- * dropped step instead of propagating, because diagnostics must not break execution.
- *
- * @param read - Getter for the current logger; omitted when the caller has no logger.
- * @param identity - Diagnostic identity copied onto each captured step.
- * @returns Frozen `subSteps`, the number of dropped steps and whether the log was truncated.
- */
-function captureSubSteps(read, identity) {
-    const empty = { subSteps: Object.freeze([]), subStepsDropped: 0, subStepsTruncated: false };
-    if (!read)
-        return empty;
-    try {
-        const logger = (0, synchronous_js_1.synchronous)(read(), 'Debug steps must be synchronous');
-        return logger === undefined
-            ? empty
-            : { ...empty, subSteps: (0, sub_flow_js_1.readSubFlowLogger)(logger, undefined, identity) };
-    }
-    catch {
-        return { ...empty, subStepsDropped: 1 };
-    }
-}