@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/support/context/history.d.ts

@@ -1,4 +1,22 @@
+/**
+ * History grouping for context reductions: split structured message arrays into atomic groups.
+ *
+ * A group is the smallest unit a trim may remove, so "fixed" counts entries while "user-turn"
+ * keeps each user message together with the assistant replies that follow it. Tool protocols are
+ * rejected because they need their own grouping contract.
+ *
+ * Main exports: `historyGrouping`, `historyGroupingCatalog`, `historyGroups` and
+ * `validateRecentHistory`.
+ */
 import type { ContextHistoryGrouping, ContextRecentHistory } from '../../structs/support/context-processing.js';
+/**
+ * Validate a grouping declaration and return it unchanged.
+ *
+ * @param options Grouping to validate.
+ * @param options.grouping Grouping kind plus its kind-specific settings.
+ * @returns The same grouping object supplied by the caller.
+ * @throws {ValidationError} When the kind is unknown or its settings are invalid.
+ */
 export declare function historyGrouping(options: {
     grouping: ContextHistoryGrouping;
 }): ContextHistoryGrouping;
@@ -6,6 +24,12 @@ declare function validateFixed(grouping: ContextHistoryGrouping): void;
 declare function fixedGroups(entries: readonly unknown[], grouping: ContextHistoryGrouping): unknown[][];
 declare function validateUserTurns(): void;
 declare function userTurns(entries: readonly unknown[]): unknown[][];
+/**
+ * Grouping kinds with their validators and splitters.
+ *
+ * Validation and splitting come from one declaration so a policy cannot pass validation with
+ * rules that the splitter does not apply.
+ */
 export declare const historyGroupingCatalog: {
     fixed: {
         validate: typeof validateFixed;
@@ -16,9 +40,28 @@ export declare const historyGroupingCatalog: {
         split: typeof userTurns;
     };
 };
+/**
+ * Split the entries of one structured field into removable groups.
+ *
+ * @param value Fragment value expected to be an object holding an array at `field`.
+ * @param options Field name and grouping rule to apply.
+ * @returns Grouped entries in source order; an empty array yields no groups.
+ * @throws {ValidationError} When the value is a string, the field is not an array, the grouping
+ *   is invalid, or the entries do not satisfy the grouping contract.
+ */
 export declare function historyGroups(value: string | Record<string, unknown>, options: {
     field: string;
     grouping: ContextHistoryGrouping;
 }): unknown[][];
+/**
+ * Validate a recent-history retention declaration.
+ *
+ * `keepGroups` may be zero (drop everything eligible); negative or fractional counts are rejected
+ * because groups are indivisible.
+ *
+ * @param options Field, retained group count and grouping rule.
+ * @throws {ValidationError} When the field is empty, `keepGroups` is invalid, or the grouping is
+ *   not recognised.
+ */
 export declare function validateRecentHistory(options: ContextRecentHistory): void;
 export {};

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

@@ -2,6 +2,14 @@ import { ValidationError } from '../../structs/errors.js';
 import { breakWhile } from '../../utils/rules.js';
 const invalid = (message) => new ValidationError([{ code: 'CONTEXT_POLICY', message }]);
 const positive = (value) => Number.isSafeInteger(value) && value > 0;
+/**
+ * Validate a grouping declaration and return it unchanged.
+ *
+ * @param options Grouping to validate.
+ * @param options.grouping Grouping kind plus its kind-specific settings.
+ * @returns The same grouping object supplied by the caller.
+ * @throws {ValidationError} When the kind is unknown or its settings are invalid.
+ */
 export function historyGrouping(options) {
     const grouping = options.grouping;
     breakWhile(!grouping || !Object.hasOwn(historyGroupingCatalog, grouping.kind), invalid('Unknown history grouping'));
@@ -24,7 +32,9 @@ function userTurns(entries) {
     const groups = [];
     for (const entry of entries) {
         const message = entry;
-        breakWhile(!message || !['user', 'assistant'].includes(message.role) || typeof message.content !== 'string', invalid('User-turn history requires user/assistant text messages; tool protocols need their own grouping contract'));
+        breakWhile(!message ||
+            !['user', 'assistant'].includes(message.role) ||
+            typeof message.content !== 'string', invalid('User-turn history requires user/assistant text messages; tool protocols need their own grouping contract'));
         if (message.role === 'user')
             groups.push([]);
         breakWhile(!groups.length, invalid('User-turn history cannot start with an orphan assistant message'));
@@ -32,15 +42,40 @@ function userTurns(entries) {
     }
     return groups;
 }
+/**
+ * Grouping kinds with their validators and splitters.
+ *
+ * Validation and splitting come from one declaration so a policy cannot pass validation with
+ * rules that the splitter does not apply.
+ */
 export const historyGroupingCatalog = {
     fixed: { validate: validateFixed, split: fixedGroups },
     'user-turn': { validate: validateUserTurns, split: userTurns },
 };
+/**
+ * Split the entries of one structured field into removable groups.
+ *
+ * @param value Fragment value expected to be an object holding an array at `field`.
+ * @param options Field name and grouping rule to apply.
+ * @returns Grouped entries in source order; an empty array yields no groups.
+ * @throws {ValidationError} When the value is a string, the field is not an array, the grouping
+ *   is invalid, or the entries do not satisfy the grouping contract.
+ */
 export function historyGroups(value, options) {
     breakWhile(typeof value === 'string' || !Array.isArray(value[options.field]), invalid('History requires a structured array field'));
     const grouping = historyGrouping(options);
     return historyGroupingCatalog[grouping.kind].split(value[options.field], grouping);
 }
+/**
+ * Validate a recent-history retention declaration.
+ *
+ * `keepGroups` may be zero (drop everything eligible); negative or fractional counts are rejected
+ * because groups are indivisible.
+ *
+ * @param options Field, retained group count and grouping rule.
+ * @throws {ValidationError} When the field is empty, `keepGroups` is invalid, or the grouping is
+ *   not recognised.
+ */
 export function validateRecentHistory(options) {
     breakWhile(!options.field || !Number.isSafeInteger(options.keepGroups) || options.keepGroups < 0, invalid('Invalid recent-history retention'));
     historyGrouping(options);

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

@@ -1,12 +1,23 @@
+/**
+ * Context support: app-side assembly, reduction and selection helpers for Core context plans.
+ *
+ * Core keeps the trust, budget, assembly and structural-audit guarantees. This module supplies
+ * recommended builders (assembly, compressor, selector, strategy) and node factories that plug
+ * into an application workflow; it does not replace Core's processing contract.
+ *
+ * Main exports: `defineContextAssembly`, `defineContextFragments`, `createContextCompressor`,
+ * `createContextSelector`, `createContextStrategy`, the context node factories and the
+ * registered policy/reduction/selection catalogs.
+ */
 export * from './assembly.js';
 export * from './fragments.js';
 export type * from '../../structs/support/context.js';
 export * from './compression.js';
 export type * from '../../structs/support/context-processing.js';
 export * from './selection.js';
-export { processContext, validateContextPolicy, contextPolicyCatalog, contextReductionCatalog } from './processing.js';
+export { processContext, validateContextPolicy, contextPolicyCatalog, contextReductionCatalog, } from './processing.js';
 export * from './selection-policy.js';
 export type { ContextPlan } from '../../structs/context/processing.js';
 export * from './nodes.js';
 export { createContextStrategy, contextHistoryStrategies } from './strategies.js';
-export type { ContextStrategy, ContextStrategyOptions, ContextStrategySettings } from './strategies.js';
+export type { ContextStrategy, ContextStrategyOptions, ContextStrategySettings, } from './strategies.js';

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

@@ -1,8 +1,19 @@
+/**
+ * Context support: app-side assembly, reduction and selection helpers for Core context plans.
+ *
+ * Core keeps the trust, budget, assembly and structural-audit guarantees. This module supplies
+ * recommended builders (assembly, compressor, selector, strategy) and node factories that plug
+ * into an application workflow; it does not replace Core's processing contract.
+ *
+ * Main exports: `defineContextAssembly`, `defineContextFragments`, `createContextCompressor`,
+ * `createContextSelector`, `createContextStrategy`, the context node factories and the
+ * registered policy/reduction/selection catalogs.
+ */
 export * from './assembly.js';
 export * from './fragments.js';
 export * from './compression.js';
 export * from './selection.js';
-export { processContext, validateContextPolicy, contextPolicyCatalog, contextReductionCatalog } from './processing.js';
+export { processContext, validateContextPolicy, contextPolicyCatalog, contextReductionCatalog, } from './processing.js';
 export * from './selection-policy.js';
 export * from './nodes.js';
 export { createContextStrategy, contextHistoryStrategies } from './strategies.js';

package/dist/esm/support/context/nodes.d.ts

@@ -3,43 +3,105 @@ import type { ContextPlan } from '../../structs/context/processing.js';
 import type { BuiltContext } from '../../structs/context/fragments.js';
 import type { ModelPrepareRequest, PreparedModelCall, ModelTransportDefinition } from '../../structs/model/runtime.js';
 import type { ContextCompressor, ContextSelector, ContextPolicy, ContextProcessingReport } from '../../structs/support/context-processing.js';
+/** Outcome of one context node: the built input, its prepared model call and the change report. */
 export interface ContextNodeResult {
+    /** Context built from the processed fragments, sized against the full input limit. */
     readonly input: BuiltContext;
+    /** Model call prepared for this stage; carries measurement and remaining call budget. */
     readonly prepared: PreparedModelCall;
+    /** What processing changed: characters, token usage, selection decisions and reductions. */
     readonly report: ContextProcessingReport;
 }
+/**
+ * Definition accepted by `createContextProcessingNode`.
+ *
+ * It is a normal Core `WorkflowNode` except that the node body is declared here: `plan` builds the
+ * context, `update` decides the committed state, and policy/handlers/timeout are validated when the
+ * node is created.
+ */
 export type ContextProcessingNodeDefinition<State, Result, App> = Omit<WorkflowNode<State, Result, App>, 'run' | 'report'> & {
+    /** Builds the context plan; must be synchronous so budget failures surface before any I/O. */
     readonly plan: (state: Readonly<State>, context: WorkflowContext<App>) => ContextPlan;
+    /** Model preparation request, either static or derived from the current node state. */
     readonly request?: (ModelPrepareRequest<string | ModelTransportDefinition> & {
         modelId?: string;
     }) | ((state: Readonly<State>, context: WorkflowContext<App>) => ModelPrepareRequest<string | ModelTransportDefinition> & {
         modelId?: string;
     });
+    /** Maps the node result to the state fields to commit; return only changed fields. */
     readonly update: (result: ContextNodeResult, state: Readonly<State>) => Partial<State>;
+    /** Optional prebuilt model call, used instead of preparing `request`. */
     readonly prepared?: (state: Readonly<State>, context: WorkflowContext<App>) => PreparedModelCall;
+    /** Processing policy; omitted means `validate` (no reduction, audit checks only). */
     readonly policy?: ContextPolicy;
+    /** Compressors referenced by compression steps; validated against the policy at creation. */
     readonly compressors?: readonly ContextCompressor[];
+    /** Selectors referenced by model-driven selection; validated against the policy at creation. */
     readonly selectors?: readonly ContextSelector[];
+    /** Per-node timeout in milliseconds; defaults to the Core call timeout. */
     readonly timeoutMs?: number;
 };
+/** Result of a selection or reduction stage, before the node's `update` commits chosen fields. */
 export interface ContextStageResult {
+    /** Plan describing current fragments at the full (unreduced) input limit. */
     readonly plan: ContextPlan;
+    /** Model call prepared for this stage. */
     readonly prepared: PreparedModelCall;
+    /** Processing report accumulated by this and preceding steps. */
     readonly report: ContextProcessingReport;
 }
+/** Selection stage result: the chosen step IDs plus the unchanged stage snapshot. */
 export interface ContextSelectionResult extends ContextStageResult {
+    /** Registered reduction step IDs chosen for execution; selection itself executes nothing. */
     readonly stepIds: readonly string[];
 }
+/** Definition of a selection node: like a processing node, but `update` receives chosen step IDs. */
 export type ContextSelectionNodeDefinition<State, Result, App> = Omit<ContextProcessingNodeDefinition<State, Result, App>, 'update'> & {
+    /** Receives the chosen step IDs so the graph can route to reduction nodes. */
     readonly update: (result: ContextSelectionResult, state: Readonly<State>) => Partial<State>;
 };
+/**
+ * Definition of a reduction node: one registered step is applied per node run.
+ *
+ * `stepId` may be fixed or derived from state, which lets a graph route over several steps.
+ */
 export type ContextReductionNodeDefinition<State, Result, App> = Omit<ContextProcessingNodeDefinition<State, Result, App>, 'update'> & {
+    /** ID of the reduction step to run, fixed or derived from state. */
     readonly stepId: string | ((state: Readonly<State>) => string);
+    /** Receives the stage result after one reduction has been applied. */
     readonly update: (result: ContextStageResult, state: Readonly<State>) => Partial<State>;
 };
-/** Recommended complete processing, or use the selection/reduction nodes for explicit graph phases. */
+/**
+ * Create one node that runs the complete context policy and returns the built context.
+ *
+ * Use this when the graph does not need to route between selection and reduction phases.
+ *
+ * @param definition Node definition including plan, model request/prepared call, policy and update.
+ * @returns A `WorkflowNode` returning the processed context, prepared call and report.
+ * @throws {Error} When the policy, its handlers or the timeout are invalid, or the plan is missing
+ *   enough input capacity.
+ */
 export declare function createContextProcessingNode<State, Result, App = undefined>(definition: ContextProcessingNodeDefinition<State, Result, App>): WorkflowNode<State, Result, App>;
-/** Selection is an ordinary node; it returns registered step IDs and does not execute reductions. */
+/**
+ * Create an ordinary node that selects reduction steps without executing them.
+ *
+ * The node reports the registered step IDs so the graph can route to reduction nodes itself.
+ *
+ * @param definition Node definition with a `reduce` policy and a selection-aware `update`.
+ * @returns A `WorkflowNode` returning the chosen step IDs plus the current stage result.
+ * @throws {Error} When the policy is not a reduction policy, a reduction target is protected, or
+ *   selection exceeds the remaining call budget.
+ */
 export declare function createContextSelectionNode<State, Result, App = undefined>(definition: ContextSelectionNodeDefinition<State, Result, App>): WorkflowNode<State, Result, App>;
-/** Executes one registered operation. Partial plans retain their budget until final assembly. */
+/**
+ * Create a node that applies exactly one registered reduction step.
+ *
+ * Partial plans keep the full budget until final assembly, so intermediate nodes do not shrink the
+ * allowance reserved for the reply.
+ *
+ * @param definition Node definition with a fixed or state-derived `stepId` and update function.
+ * @returns A `WorkflowNode` returning the stage result after the reduction.
+ * @throws {Error} When the step ID is not registered, the target is protected, or the reduction
+ *   fails or increases the fragment size.
+ */
 export declare function createContextReductionNode<State, Result, App = undefined>(definition: ContextReductionNodeDefinition<State, Result, App>): WorkflowNode<State, Result, App>;

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

@@ -1,17 +1,41 @@
-import { beginContextProcessing, finishContextProcessing, chooseSteps, applyReduction, needsReduction, watermarks, validateReductionTargets, contextPolicyCatalog, validateContextPolicy } from './processing.js';
+/**
+ * Context workflow nodes: wire context planning, processing, selection and reduction into Core.
+ *
+ * Each factory returns a standard `WorkflowNode` that prepares the model call, converts the plan
+ * into a Core processing state and then applies one stage. Applications may use the single
+ * complete node or the explicit selection/reduction pair in their own graph. The nodes add no new
+ * scheduling contract; Core still owns budgets, cancellation and commit.
+ *
+ * Main exports: `createContextProcessingNode`, `createContextSelectionNode`,
+ * `createContextReductionNode` and their result/definition types.
+ */
+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';
 import { combineSignals } from '../../utils/cancellation.js';
 import { breakWhile } from '../../utils/rules.js';
 function history(source) {
     const grouping = source.grouping;
-    return { field: source.field, keepGroups: source.keepGroups,
-        grouping: grouping.kind === 'fixed' ? { kind: grouping.kind, size: grouping.size } : { kind: grouping.kind } };
+    return {
+        field: source.field,
+        keepGroups: source.keepGroups,
+        grouping: grouping.kind === 'fixed'
+            ? { kind: grouping.kind, size: grouping.size }
+            : { kind: grouping.kind },
+    };
 }
 function reduction(source) {
     const { id, kind, fragmentId, targetChars } = source;
-    return kind === 'trim' ? { id, kind, fragmentId, targetChars, ...history(source) }
-        : { id, kind, fragmentId, targetChars, handlerId: source.handlerId, preserve: source.preserve && history(source.preserve) };
+    return kind === 'trim'
+        ? { id, kind, fragmentId, targetChars, ...history(source) }
+        : {
+            id,
+            kind,
+            fragmentId,
+            targetChars,
+            handlerId: source.handlerId,
+            preserve: source.preserve && history(source.preserve),
+        };
 }
 function policySnapshot(source) {
     if (source.mode === 'audit')
@@ -19,74 +43,168 @@ function policySnapshot(source) {
     if (source.mode !== 'reduce')
         return { mode: source.mode };
     const selection = source.selection;
-    return { mode: source.mode, triggerChars: source.triggerChars, targetInputChars: source.targetInputChars,
-        triggerTokens: source.triggerTokens, targetInputTokens: source.targetInputTokens, steps: source.steps.map(reduction),
-        selection: !selection ? undefined : selection.mode === 'fixed' ? { mode: selection.mode, kind: selection.kind }
-            : selection.mode === 'auto' ? { mode: selection.mode, reserveCalls: selection.reserveCalls, maxTrimLossRatio: selection.maxTrimLossRatio }
-                : selection.mode === 'model' ? { mode: selection.mode, reserveCalls: selection.reserveCalls, handlerId: selection.handlerId } : { mode: selection.mode } };
+    return {
+        mode: source.mode,
+        triggerChars: source.triggerChars,
+        targetInputChars: source.targetInputChars,
+        triggerTokens: source.triggerTokens,
+        targetInputTokens: source.targetInputTokens,
+        steps: source.steps.map(reduction),
+        selection: !selection
+            ? undefined
+            : selection.mode === 'fixed'
+                ? { mode: selection.mode, kind: selection.kind }
+                : selection.mode === 'auto'
+                    ? {
+                        mode: selection.mode,
+                        reserveCalls: selection.reserveCalls,
+                        maxTrimLossRatio: selection.maxTrimLossRatio,
+                    }
+                    : selection.mode === 'model'
+                        ? {
+                            mode: selection.mode,
+                            reserveCalls: selection.reserveCalls,
+                            handlerId: selection.handlerId,
+                        }
+                        : { mode: selection.mode },
+    };
 }
 function stageResult(work, prepared, fullLimit, steps) {
-    const mutable = steps.map(step => step.fragmentId);
-    return { plan: { additionalMessages: work.plan.additionalMessages, fragments: work.fragments, maxInputChars: fullLimit,
-            originalFragments: work.plan.originalFragments ?? work.before, mutableFragmentIds: [...new Set(mutable)] },
-        prepared, report: work.report };
+    const mutable = steps.map((step) => step.fragmentId);
+    return {
+        plan: {
+            additionalMessages: work.plan.additionalMessages,
+            fragments: work.fragments,
+            maxInputChars: fullLimit,
+            originalFragments: work.plan.originalFragments ?? work.before,
+            // Several steps may target one fragment; the plan lists each mutable ID only once.
+            mutableFragmentIds: [...new Set(mutable)],
+        },
+        prepared,
+        report: work.report,
+    };
 }
 /** Common node wiring only; each specialized creator supplies its actual algorithm. */
 function contextNode(definition, execute) {
     const plan = definition.plan.bind(definition), update = definition.update.bind(definition);
     const selectPrepared = definition.prepared?.bind(definition);
     const requestSource = definition.request;
-    const request = typeof requestSource === 'function' ? requestSource.bind(definition) : {
-        stageId: requestSource?.stageId, modelId: requestSource?.modelId, transport: requestSource?.transport, maxOutputTokens: requestSource?.maxOutputTokens,
-    };
+    const request = typeof requestSource === 'function'
+        ? requestSource.bind(definition)
+        : {
+            stageId: requestSource?.stageId,
+            modelId: requestSource?.modelId,
+            transport: requestSource?.transport,
+            maxOutputTokens: requestSource?.maxOutputTokens,
+        };
     const policy = policySnapshot(definition.policy ?? { mode: 'validate' });
-    const compressors = (definition.compressors ?? []).map(handler => {
+    const compressors = (definition.compressors ?? []).map((handler) => {
         const { id, maxCalls, compress } = handler;
-        return { id, maxCalls, compress: typeof compress === 'function' ? compress.bind(handler) : compress };
+        return {
+            id,
+            maxCalls,
+            compress: typeof compress === 'function' ? compress.bind(handler) : compress,
+        };
     });
-    const selectors = (definition.selectors ?? []).map(handler => {
+    const selectors = (definition.selectors ?? []).map((handler) => {
         const { id, maxCalls, select } = handler;
         return { id, maxCalls, select: typeof select === 'function' ? select.bind(handler) : select };
     });
     validateContextPolicy(policy, compressors, selectors);
     const timeoutMs = definition.timeoutMs ?? modelRunnerDefaults.callTimeoutMs;
     breakWhile(!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647, 'Invalid context node timeout');
-    return { id: definition.id, description: definition.description, name: definition.name,
-        startsRound: definition.startsRound, requires: definition.requires, provides: definition.provides,
-        onErrorNodeId: definition.onErrorNodeId, onErrorRouteId: definition.onErrorRouteId, routes: definition.routes,
+    return {
+        id: definition.id,
+        description: definition.description,
+        name: definition.name,
+        startsRound: definition.startsRound,
+        requires: definition.requires,
+        provides: definition.provides,
+        onErrorNodeId: definition.onErrorNodeId,
+        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 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,
+            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, signal }),
-                ...(overhead.counterId ? { tokenBudget: { counterId: overhead.counterId, inputLimit: overhead.inputTokenLimit,
-                        measure: messages => prepared.measure(messages).inputTokens } } : {}),
+                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');
         },
     };
 }
-/** Recommended complete processing, or use the selection/reduction nodes for explicit graph phases. */
+/**
+ * Create one node that runs the complete context policy and returns the built context.
+ *
+ * Use this when the graph does not need to route between selection and reduction phases.
+ *
+ * @param definition Node definition including plan, model request/prepared call, policy and update.
+ * @returns A `WorkflowNode` returning the processed context, prepared call and report.
+ * @throws {Error} When the policy, its handlers or the timeout are invalid, or the plan is missing
+ *   enough input capacity.
+ */
 export function createContextProcessingNode(definition) {
     return contextNode(definition, async (work, prepared, fullLimit) => {
         await contextPolicyCatalog[work.policy.mode].run(work);
         const result = finishContextProcessing(work);
-        return { input: { ...result.context, maxInputChars: fullLimit }, prepared, report: result.report };
+        return {
+            input: { ...result.context, maxInputChars: fullLimit },
+            prepared,
+            report: result.report,
+        };
     });
 }
-/** Selection is an ordinary node; it returns registered step IDs and does not execute reductions. */
+/**
+ * Create an ordinary node that selects reduction steps without executing them.
+ *
+ * The node reports the registered step IDs so the graph can route to reduction nodes itself.
+ *
+ * @param definition Node definition with a `reduce` policy and a selection-aware `update`.
+ * @returns A `WorkflowNode` returning the chosen step IDs plus the current stage result.
+ * @throws {Error} When the policy is not a reduction policy, a reduction target is protected, or
+ *   selection exceeds the remaining call budget.
+ */
 export function createContextSelectionNode(definition) {
     return contextNode(definition, async (work, prepared, fullLimit) => {
         validateReductionTargets(work);
@@ -95,11 +213,22 @@ export function createContextSelectionNode(definition) {
         work.report.selection = policy.selection?.mode ?? 'sequence';
         work.report.decisions = [];
         const stepIds = needsReduction(work, watermarks(work).trigger)
-            ? await chooseSteps(work, policy.steps, policy.selection ?? { mode: 'sequence' }) : [];
+            ? await chooseSteps(work, policy.steps, policy.selection ?? { mode: 'sequence' })
+            : [];
         return { ...stageResult(work, prepared, fullLimit, policy.steps), stepIds };
     });
 }
-/** Executes one registered operation. Partial plans retain their budget until final assembly. */
+/**
+ * Create a node that applies exactly one registered reduction step.
+ *
+ * Partial plans keep the full budget until final assembly, so intermediate nodes do not shrink the
+ * allowance reserved for the reply.
+ *
+ * @param definition Node definition with a fixed or state-derived `stepId` and update function.
+ * @returns A `WorkflowNode` returning the stage result after the reduction.
+ * @throws {Error} When the step ID is not registered, the target is protected, or the reduction
+ *   fails or increases the fragment size.
+ */
 export function createContextReductionNode(definition) {
     const source = definition.stepId;
     const stepId = typeof source === 'function' ? source.bind(definition) : () => source;
@@ -107,7 +236,7 @@ export function createContextReductionNode(definition) {
         validateReductionTargets(work);
         const policy = work.policy;
         const id = synchronous(stepId(state), 'Context operation IDs must be synchronous');
-        const step = policy.steps.find(item => item.id === id);
+        const step = policy.steps.find((item) => item.id === id);
         breakWhile(!step, 'Context operation is not registered');
         await applyReduction(work, step, policy.selection ?? { mode: 'sequence' });
         return stageResult(work, prepared, fullLimit, policy.steps);