@jangts/agent-core 0.1.0 → 0.2.0

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

@@ -2,7 +2,18 @@ import type { ContextPlan } from '../../structs/context/processing.js';
 import type { ModelMessage } from '../../structs/model/messages.js';
 import type { ContextFragment, BuiltContext } from '../../structs/context/fragments.js';
 import type { ContextPolicy, ContextReduction, ContextCompressor, ContextModelCall, ContextProcessingReport, ContextSelector, ContextSelection } from '../../structs/support/context-processing.js';
-/** Validate a finite ordered plan once; no application names or model prompts in Core. */
+/**
+ * Validate a complete context policy and every handler it can reference.
+ *
+ * Handler IDs must be unique and each handler must declare a non-negative integer call ceiling.
+ * Reduction targets and selection modes are checked by their own catalog entries.
+ *
+ * @param policy Policy to validate; the mode must be one of the registered modes.
+ * @param compressors Compressors available to compression steps.
+ * @param selectors Selectors available to model-driven selection.
+ * @throws {ValidationError} When a handler, mode, reduction step or selection declaration is
+ *   invalid or references something unregistered.
+ */
 export declare function validateContextPolicy(policy: ContextPolicy, compressors: readonly ContextCompressor[], selectors?: readonly ContextSelector[]): void;
 declare function validateCorePolicy(policy: ContextPolicy, handlers: Set<string>): void;
 interface OperationCall {
@@ -27,19 +38,49 @@ export declare const contextReductionCatalog: {
         run: typeof compress;
     };
 };
+/**
+ * Validate fragment structure and ID uniqueness without re-checking per-fragment budgets.
+ *
+ * Per-fragment size is rechecked during reduction, where the fragment's own allowance applies.
+ *
+ * @param fragments Fragments to validate as one set.
+ * @throws {ValidationError} When an ID is malformed or repeated, or required metadata is invalid.
+ */
 export declare function validateStructure(fragments: readonly ContextFragment[]): void;
+/** Execution ports accepted by the processing helpers; alias of the Core options contract. */
 export type ProcessingPorts = import('../../structs/support/context-processing.js').ContextProcessingOptions;
 export interface ProcessingState {
+    /** Token count before processing; present only when a token measurement port was supplied. */
     beforeTokens?: number;
+    /** Normalized plan the state was created from. */
     plan: ContextPlan;
+    /** Policy under execution; already validated and snapshotted. */
     policy: ContextPolicy;
+    /** Execution ports: signal, diagnostics, call budget and model call. */
     ports: ProcessingPorts;
+    /** Cloned user messages appended after fragments and counted against the same budget. */
     additionalMessages: ModelMessage[];
+    /** Total characters across `additionalMessages`. */
     additionalChars: number;
+    /** Original fragment snapshot, retained for audit and reporting. */
     before: ContextFragment[];
+    /** Working fragments; reductions replace entries in this array. */
     fragments: ContextFragment[];
+    /** Accumulates changes, selection decisions and token measurements. */
     report: ContextProcessingReport;
 }
+/**
+ * Resolve the effective trigger and target watermarks for a reduction policy.
+ *
+ * Configured values are clamped to the plan's character budget and the runner's token limit, so a
+ * policy can never reduce below what the request actually allows. A missing target equals the
+ * trigger, which means "reduce until back under the trigger".
+ *
+ * @param state Processing state carrying the plan and ports.
+ * @returns Trigger and target sizes in characters and, when measurable, tokens.
+ * @throws {ValidationError} When token thresholds are configured without a token measurement port,
+ *   or the effective target exceeds the effective trigger.
+ */
 export declare function watermarks(state: ProcessingState): {
     trigger: {
         chars: number;
@@ -50,14 +91,82 @@ export declare function watermarks(state: ProcessingState): {
         tokens: number | undefined;
     };
 };
+/**
+ * Decide whether the current fragments still need reduction.
+ *
+ * A fragment exceeding its own `maxChars` also counts as needing reduction, even when the total
+ * fits, because per-fragment allowances are part of the plan contract.
+ *
+ * @param state Processing state to measure.
+ * @param threshold Trigger size; `tokens` is checked only when present.
+ * @returns `true` when characters, a per-fragment allowance or tokens exceed the threshold.
+ */
 export declare function needsReduction(state: ProcessingState, threshold: {
     chars: number;
     tokens?: number;
 }): boolean;
+/**
+ * Validate and record application-made changes for an `audit` policy.
+ *
+ * Only fragments listed as mutable may have changed; the audit helper enforces the rest. Changes
+ * that survive are recorded in the report as `app` entries.
+ *
+ * @param state Processing state; the policy must be `audit` and carry original fragments.
+ * @throws {ValidationError} When the policy is not `audit`, original fragments are missing, a
+ *   mutable ID does not exist, or a protected fragment changed.
+ */
 export declare function auditApp({ plan, policy, before, fragments, report }: ProcessingState): void;
+/**
+ * Wrap the model call port with a handler-local call ceiling and a reply reserve.
+ *
+ * `reserve` is subtracted from the runner's remaining budget, so handlers can never consume the
+ * calls the final reply still needs.
+ *
+ * @param ports Execution ports providing cancellation and the underlying model call.
+ * @param maxCalls Maximum calls this handler may make.
+ * @param reserve Calls that must remain available for the reply.
+ * @returns A call function that throws instead of overspending.
+ * @throws {BudgetError} On each call that would exceed either limit.
+ * @throws The signal's abort reason when the request is already cancelled.
+ */
 export declare function limitedCall(ports: ProcessingPorts, maxCalls: number, reserve: number): ContextModelCall;
+/**
+ * Choose which reduction steps to run next, under the current selection mode.
+ *
+ * Candidates that cannot make progress are filtered out: a step whose fragment already fits, a
+ * compression with no older history, or a step that needs more calls than the remaining budget.
+ *
+ * @param state Processing state providing ports, fragments and the report.
+ * @param steps Reduction steps still pending.
+ * @param selection Selection strategy to apply.
+ * @returns Registered step IDs in execution order; records the decision in the report.
+ * @throws {BudgetError} When model-driven selection has no calls or no feasible candidate left.
+ * @throws {ValidationError} When the selector returns unknown, duplicate or over-budget IDs.
+ */
 export declare function chooseSteps(state: ProcessingState, steps: readonly ContextReduction[], selection: ContextSelection): Promise<string[]>;
+/**
+ * Apply one reduction step to its target fragment in the working state.
+ *
+ * The fragment is cloned before the handler runs, then validated, audited and size-checked before
+ * it replaces the original. A reduction that grows the fragment is rejected.
+ *
+ * @param state Processing state whose fragments are updated in place.
+ * @param step Reduction step to execute.
+ * @param selection Selection strategy used to size the handler call budget.
+ * @throws {ValidationError} When the result is structurally invalid, changes protected fields, or
+ *   exceeds the original size.
+ * @throws {BudgetError} When the step's handler exceeds its call allowance.
+ */
 export declare function applyReduction(state: ProcessingState, step: ContextReduction, selection: ContextSelection): Promise<void>;
+/**
+ * Check that every reduction step targets an existing, reducible fragment.
+ *
+ * System-role and instruction-trust fragments are never reducible, regardless of policy.
+ *
+ * @param state Processing state whose policy and fragments are checked.
+ * @throws {ValidationError} When the policy is not a reduction policy or a target is missing,
+ *   system-owned or instruction-trusted.
+ */
 export declare function validateReductionTargets(state: ProcessingState): void;
 declare function reduceCore(state: ProcessingState): Promise<void>;
 declare function validateAppPolicy(policy: ContextPolicy): void;
@@ -76,11 +185,46 @@ export declare const contextPolicyCatalog: {
         run: typeof auditApp;
     };
 };
+/**
+ * Snapshot and validate a plan before any reduction runs.
+ *
+ * Messages and fragments are cloned and their getters read inside cancellation checks, so a late
+ * abort cannot leave partially copied state. Additional messages must be plain user text.
+ *
+ * @param source Plan supplied by the request or a context builder.
+ * @param policy Validated policy to execute.
+ * @param ports Execution ports for cancellation, diagnostics and model calls.
+ * @returns A processing state ready for the policy runner.
+ * @throws {ValidationError} When the budget, fragments, additional messages or token budget are
+ *   invalid, or a protected fragment already changed.
+ * @throws {TypeError} When the plan budget is not a valid integer or infinity.
+ */
 export declare function beginContextProcessing(source: ContextPlan, policy: ContextPolicy, ports: ProcessingPorts): ProcessingState;
+/**
+ * Assemble the final context and finalize the processing report.
+ *
+ * Additional messages are appended after fragments, and the combined size is checked against the
+ * same budget. Token measurements are reported only when a measurement port exists.
+ *
+ * @param state Processing state after the policy has run.
+ * @returns The built context and the completed report.
+ * @throws {ValidationError} When the final input exceeds the character budget or, with a token
+ *   counter, the token budget (code `MODEL_TOKEN_BUDGET`).
+ */
 export declare function finishContextProcessing(state: ProcessingState): {
     context: BuiltContext;
     report: ContextProcessingReport;
 };
+/**
+ * Run a complete context policy in one call: snapshot, execute and finalize.
+ *
+ * @param plan Plan to process.
+ * @param policy Policy whose mode selects the registered runner.
+ * @param ports Execution ports for cancellation, diagnostics and model calls.
+ * @returns The processed context and its report.
+ * @throws {ValidationError} When validation or the final budget check fails.
+ * @throws {BudgetError} When a handler exhausts its call allowance.
+ */
 export declare function processContext(plan: ContextPlan, policy: ContextPolicy, ports: ProcessingPorts): Promise<{
     context: BuiltContext;
     report: ContextProcessingReport;