@jangts/agent-core 0.1.1 → 0.2.0

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

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createContextProcessingNode = createContextProcessingNode;
 exports.createContextSelectionNode = createContextSelectionNode;
 exports.createContextReductionNode = createContextReductionNode;
+/**
+ * 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.
+ */
 const processing_js_1 = require("./processing.js");
 const defaults_js_1 = require("../../model/defaults.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
@@ -10,13 +21,26 @@ const cancellation_js_1 = require("../../utils/cancellation.js");
 const rules_js_1 = require("../../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')
@@ -24,74 +48,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 };
     });
     (0, processing_js_1.validateContextPolicy)(policy, compressors, selectors);
     const timeoutMs = definition.timeoutMs ?? defaults_js_1.modelRunnerDefaults.callTimeoutMs;
     (0, rules_js_1.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 = (0, cancellation_js_1.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 = (0, synchronous_js_1.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;
             (0, rules_js_1.breakWhile)(bodyLimit < 1, 'No input capacity for context');
-            const work = (0, processing_js_1.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 = (0, processing_js_1.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 (0, synchronous_js_1.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.
+ */
 function createContextProcessingNode(definition) {
     return contextNode(definition, async (work, prepared, fullLimit) => {
         await processing_js_1.contextPolicyCatalog[work.policy.mode].run(work);
         const result = (0, processing_js_1.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.
+ */
 function createContextSelectionNode(definition) {
     return contextNode(definition, async (work, prepared, fullLimit) => {
         (0, processing_js_1.validateReductionTargets)(work);
@@ -100,11 +218,22 @@ function createContextSelectionNode(definition) {
         work.report.selection = policy.selection?.mode ?? 'sequence';
         work.report.decisions = [];
         const stepIds = (0, processing_js_1.needsReduction)(work, (0, processing_js_1.watermarks)(work).trigger)
-            ? await (0, processing_js_1.chooseSteps)(work, policy.steps, policy.selection ?? { mode: 'sequence' }) : [];
+            ? await (0, processing_js_1.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.
+ */
 function createContextReductionNode(definition) {
     const source = definition.stepId;
     const stepId = typeof source === 'function' ? source.bind(definition) : () => source;
@@ -112,7 +241,7 @@ function createContextReductionNode(definition) {
         (0, processing_js_1.validateReductionTargets)(work);
         const policy = work.policy;
         const id = (0, synchronous_js_1.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);
         (0, rules_js_1.breakWhile)(!step, 'Context operation is not registered');
         await (0, processing_js_1.applyReduction)(work, step, policy.selection ?? { mode: 'sequence' });
         return stageResult(work, prepared, fullLimit, policy.steps);