@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/structs/support/registration.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Conditional registration contract.
+ *
+ * Place in the package: Support-side composition for App install steps. Steps are validated once,
+ * then installed in order per invocation; a predicate may only observe what earlier steps already
+ * installed, so declaration order is part of the contract. No new scheduling protocol is defined.
+ *
+ * Exports: `RegistrationDefinition`.
+ */
+/** One install step. */
 export interface RegistrationDefinition<Context> {
+    /** Unique step id; also the catalog key. */
     readonly id: string;
+    /** Installs the step when true; must be synchronous and is re-evaluated per install. */
     readonly when?: (context: Context) => boolean;
+    /** Performs the installation; must return void synchronously. */
     readonly register: (context: Context) => void;
 }

package/dist/esm/structs/support/schema.d.ts

@@ -1,9 +1,23 @@
+/**
+ * Schema adapter contract.
+ *
+ * Place in the package: Support-side adapters that turn an App's JSON Schema compiler or parsing
+ * library into the Core `SchemaAdapter` shape. The compiler, package and error messages stay
+ * application choices; schema snapshots are frozen before they reach the compiler.
+ *
+ * Exports: `JsonSchemaValidator`, `JsonSchemaOptions`.
+ */
 /** App-owned JSON Schema compilers provide synchronous validation. */
 export interface JsonSchemaValidator<Output = unknown> {
+    /** Returns whether the value is valid; must be synchronous. */
     (value: unknown): value is Output;
+    /** Compiler-reported details for the last failed validation, when the library exposes them. */
     readonly errors?: unknown;
 }
+/** Options for building an adapter from a JSON Schema compiler. */
 export interface JsonSchemaOptions<Output> {
+    /** Compiles a frozen schema copy into a validator; must return synchronously. */
     compile(schema: Record<string, unknown>): JsonSchemaValidator<Output>;
+    /** Builds the thrown error for an invalid value; defaults to a `TypeError`. */
     error?(value: unknown, errors: unknown): Error;
 }

package/dist/esm/structs/support/tools.d.ts

@@ -1,28 +1,47 @@
+/**
+ * Tool catalog contract used by Support's tool assembly.
+ *
+ * Place in the package: an App-side projection of typed tool definitions into model capabilities.
+ * The model may only propose `{ toolId, input }`; authorization, invocation, budgets and
+ * cancellation still happen in Core's tool registry.
+ *
+ * Exports: `ToolDefinition` (type re-export), `ToolProposal`, `ToolCapabilities`, `SelectedTools`,
+ * `ToolOutput`, `CompiledTool`, `ToolRuntime`, `ToolCatalogEntry`, `ToolCatalog`.
+ */
 import type { ToolResult } from '../invocation.js';
 import type { SchemaAdapter, ExecutionOptions, ReadonlyCatalog } from '../common.js';
 import type { RegisteredModelCapability, ModelSelection } from '../capabilities/model.js';
 import type { ModelCapabilityRegistry } from '../../capabilities/model.js';
 import type { ToolDefinition, ToolExecutionEvent, ToolRegistryPorts, ToolInvocationRequest } from '../capabilities/tools.js';
 export type { ToolDefinition } from '../capabilities/tools.js';
+/** A model's proposal to call one tool; nothing has been authorized or executed yet. */
 export interface ToolProposal {
+    /** Registered tool the model selected. */
     readonly toolId: string;
+    /** Raw arguments; schema parsing and authorization happen in Core. */
     readonly input: unknown;
 }
+/** Model capability view of a tool catalog. */
 export interface ToolCapabilities extends ModelCapabilityRegistry {
     values(): IterableIterator<RegisteredModelCapability<ToolProposal>>;
+    /** Resolves a model selection into a proposal; throws for unknown or invalid selections. */
     resolve(selection: ModelSelection, context: Readonly<{
         stageId: string;
     }>): ToolProposal;
+    /** Narrows the capability set to `ids`; throws for unregistered ids. */
     select(ids: readonly string[]): ToolCapabilities;
 }
 type ResultDefinition = {
     readonly id: string;
     parseOutput(value: unknown): unknown;
 };
+/** Catalog narrowed to the given ids: each kept tool's id literal is intersected with `Id`. */
 export type SelectedTools<Tool extends ResultDefinition, Id extends string> = Tool extends ResultDefinition ? [Tool['id'] & Id] extends [never] ? never : Tool & {
     readonly id: Tool['id'] & Id;
 } : never;
+/** Output type of the tool whose id matches `Id`; `never` for any other id. */
 export type ToolOutput<Tool extends ResultDefinition, Id extends string> = Tool extends ResultDefinition ? Id extends Tool['id'] ? ReturnType<Tool['parseOutput']> : never : never;
+/** Tool definition type derived from a declaration literal, preserving input/output/id. */
 export type CompiledTool<App, Definition> = Definition extends {
     parseOutput(value: unknown): infer Output;
 } ? Definition extends {
@@ -30,18 +49,27 @@ export type CompiledTool<App, Definition> = Definition extends {
 } ? ToolDefinition<Definition extends {
     inputSchema: SchemaAdapter<infer Input>;
 } ? Input : unknown, Output, App, Id> : never : never;
+/** Catalog bound to one App request. */
 export interface ToolRuntime<Tool extends ResultDefinition = ResultDefinition> {
+    /** The catalog's model capabilities, shared with the catalog instance. */
     readonly capabilities: ToolCapabilities;
+    /** Execution events recorded by this runtime so far, in occurrence order. */
     readonly events: readonly ToolExecutionEvent[];
+    /** Synchronous invocation; rejects tools declared as asynchronous. */
     invokeSync<const Id extends Tool['id']>(request: ToolInvocationRequest<Id>): ToolResult<ToolOutput<Tool, Id>>;
     invokeSync(request: ToolInvocationRequest): ToolResult<unknown>;
+    /** Asynchronous invocation; still bounded by the bound execution signal and errors. */
     invoke<const Id extends Tool['id']>(request: ToolInvocationRequest<Id>): Promise<ToolResult<ToolOutput<Tool, Id>>>;
     invoke(request: ToolInvocationRequest): Promise<ToolResult<unknown>>;
 }
+/** Public declaration surface of one tool, without registry internals. */
 export type ToolCatalogEntry<App, Tool extends ToolDefinition<unknown, unknown, App>> = Tool extends ToolDefinition<unknown, unknown, App> ? Pick<Tool, keyof ToolDefinition<unknown, unknown, App>> : never;
+/** Frozen tool catalog with model capabilities and per-request binding. */
 export interface ToolCatalog<App, Tool extends ToolDefinition<unknown, unknown, App> = ToolDefinition<unknown, unknown, App>> extends ReadonlyCatalog<ToolCatalogEntry<App, Tool>> {
     readonly capabilities: ToolCapabilities;
+    /** Narrows the catalog while preserving declaration order; throws for unknown ids. */
     select<const Ids extends readonly string[]>(ids: Ids): ToolCatalog<App, SelectedTools<Tool, Ids[number]>>;
+    /** Binds the catalog to one App request and returns an invocable runtime. */
     bind(request: {
         app: App;
         execution?: ExecutionOptions;

package/dist/esm/structs/support/transport/json.d.ts

@@ -1,7 +1,23 @@
+/**
+ * JSON transport framing contract.
+ *
+ * Place in the package: Support-side helpers that locate complete JSON objects inside streamed
+ * text. Framing is mechanical and never repairs or interprets fields; the caller decides which
+ * outside content and frames are acceptable. Limits prevent malformed streams from consuming
+ * unbounded memory.
+ *
+ * Exports: `JsonFrameLimits`, `JsonTransportPart`.
+ */
+/** Bounds applied while scanning a streamed text. */
 export interface JsonFrameLimits {
+    /** Maximum number of complete frames accepted. */
     maxFrames: number;
+    /** Stray closing braces tolerated outside frames, covering transports that repeat a delimiter. */
     maxExtraClosings: number;
+    /** Optional per-frame character cap so a single frame cannot amplify into an oversized parse. */
+    maxFrameChars?: number;
 }
+/** One scanned span: a complete object frame or a character outside any frame. */
 export type JsonTransportPart = {
     kind: 'frame' | 'outside';
     text: string;

package/dist/esm/structs/support/transport/sse.d.ts

@@ -1,9 +1,24 @@
+/**
+ * Server-sent event transport contract.
+ *
+ * Place in the package: Support-side framing only. The host owns its HTTP response and lifecycle;
+ * these types let Support encode frames and wait for backpressure in a cancellable way, while
+ * reading is delegated to the shared streaming package.
+ *
+ * Exports: `SseEvent` and `SseReadOptions` (type re-exports), `SseWriter`, `SseOutputEvent`.
+ */
 export type { SseEvent, SseReadOptions } from '@jangts/streaming/sse';
+/** Destination that reports backpressure instead of buffering without bound. */
 export interface SseWriter {
+    /** Writes one encoded frame; returns false when the consumer needs a drain wait. */
     write(frame: string): boolean;
+    /** Resolves once the destination can accept more data, or rejects when `signal` aborts. */
     waitForDrain(signal?: AbortSignal): Promise<unknown>;
 }
+/** One outbound event before wire encoding. */
 export interface SseOutputEvent {
+    /** Event name; must not contain a line break. */
     event: string;
+    /** Payload text; each line becomes its own `data:` field. */
     data: string;
 }

package/dist/esm/structs/utils/rules.d.ts

@@ -1,13 +1,26 @@
+/**
+ * Shared rule vocabulary for ordered matching, traversal and rejection checks.
+ *
+ * Place in the package: Core-level primitives used by both Core and Support. They describe rule
+ * lists only; the helper that executes them lives in `utils/rules.ts`, so a declaration stays
+ * readable without importing behaviour.
+ *
+ * Exports: `MatchRule`, `WalkRule`, `BreakReason`, `BreakPredicate`, `BreakCheck`, `BreakEvent`,
+ * `BreakWhileConfig`.
+ */
 /** Order is priority. Patterns may inspect values, types, state or regular expressions. */
 export interface MatchRule<Input, Result = void> {
+    /** Unique rule id used in diagnostics. */
     readonly id: string;
     readonly description: string;
     /** Omission is an unconditional match at this position, normally the final fallback. */
     readonly pattern?: (input: Readonly<Input>) => boolean;
+    /** Produces the rule's result; only the first matching rule runs. */
     readonly handle: (input: Input) => Result;
 }
 /** Synchronous traversal; local rules may omit catalog metadata. */
 export interface WalkRule<Input = void> extends Partial<MatchRule<Input, unknown>> {
+    /** Runs when the rule matches; must return synchronously. */
     readonly handle: (input: Input) => unknown;
     /** Runs before matching, including when the rule does not match. */
     readonly before?: (input: Input) => void;
@@ -20,14 +33,20 @@ export type BreakPredicate = () => unknown;
 export interface BreakCheck {
     /** A truthy failure, lazy predicate, or ordered OR-list of lazy predicates. */
     readonly occur: unknown;
+    /** Rejection reason; omitted means the helper creates a default `Error`. */
     readonly error?: BreakReason;
+    /** Tags attributed to the rejection, merged with the enclosing group's tags. */
     readonly tags?: readonly string[];
 }
 /** Diagnostic metadata only; rule inputs and request data are not included. */
 export interface BreakEvent {
+    /** The thrown value, kept for identity. */
     readonly error: unknown;
+    /** Tags of the check that rejected, plus its enclosing group tags. */
     readonly tags: readonly string[];
 }
+/** Global rejection observer installed once per process. */
 export interface BreakWhileConfig {
+    /** Called before the reason is thrown; its errors are swallowed and promises are not awaited. */
     readonly onBreak?: (event: BreakEvent) => void | Promise<void>;
 }

package/dist/esm/support/capabilities.d.ts

@@ -1,7 +1,30 @@
 import type { CapabilityModule, CapabilityCatalogOptions, CapabilityToolReferences } from '../structs/support/capabilities.js';
-/** Validate against the complete registered set, including tools unavailable in this request. */
+/**
+ * Validate tool references against the complete registered set.
+ *
+ * Checking against every registered tool (not only the ones available in the current request)
+ * keeps the declaration honest: a module may reference a tool that this request filters out, but
+ * never one that does not exist.
+ *
+ * @param names All registered tool IDs, including tools unavailable to the current request.
+ * @param references Tool-reference declarations to check.
+ * @throws {Error} When an owner ID is blank, `requiredToolIds` is not an array, or a referenced
+ *   tool ID is not registered.
+ */
 export declare function validateToolReferences(names: Iterable<string>, references: readonly CapabilityToolReferences[]): void;
-/** App-side composition only: no new Core execution entity or domain lifecycle. */
+/**
+ * Build a frozen capability catalog from application module declarations.
+ *
+ * Each module must carry a non-empty description, and every contributed tool ID must be unique
+ * across modules. Reference projections run during construction and must be synchronous.
+ *
+ * @param definitions Capability modules in declaration order; order is preserved in the catalog.
+ * @param options Optional projections that expose tool references for validation.
+ * @returns A frozen catalog with `definitions`, `require`, `tools` and `findToolOwner`.
+ * @throws {TypeError} When the catalog lookup receives an unknown module ID.
+ * @throws {Error} When a module description, tool ID, reference projection or referenced tool is
+ *   invalid.
+ */
 export declare function defineCapabilityCatalog<Module extends CapabilityModule>(definitions: readonly Module[], options?: CapabilityCatalogOptions<Module>): Readonly<{
     tools: readonly Module["tools"][number][];
     findToolOwner(toolId: string): Readonly<Module> | undefined;

package/dist/esm/support/capabilities.js

@@ -1,7 +1,27 @@
+/**
+ * Capability catalog support: validate application modules and the tools they contribute.
+ *
+ * Applications declare modules (id, description, tools) plus optional tool-reference projections;
+ * this module checks them once at construction so the resulting catalog can be handed to Core.
+ * It is composition only: it creates no Core execution entity and owns no domain lifecycle.
+ *
+ * Main exports: `defineCapabilityCatalog` and `validateToolReferences`.
+ */
 import { synchronous } from '../utils/synchronous.js';
 import { readonlyCatalog } from '../utils/catalog.js';
 import { breakWhile } from '../utils/rules.js';
-/** Validate against the complete registered set, including tools unavailable in this request. */
+/**
+ * Validate tool references against the complete registered set.
+ *
+ * Checking against every registered tool (not only the ones available in the current request)
+ * keeps the declaration honest: a module may reference a tool that this request filters out, but
+ * never one that does not exist.
+ *
+ * @param names All registered tool IDs, including tools unavailable to the current request.
+ * @param references Tool-reference declarations to check.
+ * @throws {Error} When an owner ID is blank, `requiredToolIds` is not an array, or a referenced
+ *   tool ID is not registered.
+ */
 export function validateToolReferences(names, references) {
     const available = new Set(names);
     for (const reference of references) {
@@ -13,9 +33,21 @@ export function validateToolReferences(names, references) {
         }
     }
 }
-/** App-side composition only: no new Core execution entity or domain lifecycle. */
+/**
+ * Build a frozen capability catalog from application module declarations.
+ *
+ * Each module must carry a non-empty description, and every contributed tool ID must be unique
+ * across modules. Reference projections run during construction and must be synchronous.
+ *
+ * @param definitions Capability modules in declaration order; order is preserved in the catalog.
+ * @param options Optional projections that expose tool references for validation.
+ * @returns A frozen catalog with `definitions`, `require`, `tools` and `findToolOwner`.
+ * @throws {TypeError} When the catalog lookup receives an unknown module ID.
+ * @throws {Error} When a module description, tool ID, reference projection or referenced tool is
+ *   invalid.
+ */
 export function defineCapabilityCatalog(definitions, options = {}) {
-    const catalog = readonlyCatalog(definitions, id => new TypeError(`Unknown capability module: ${id}`));
+    const catalog = readonlyCatalog(definitions, (id) => new TypeError(`Unknown capability module: ${id}`));
     const modules = catalog.definitions;
     const owners = new Map();
     const tools = [];
@@ -28,9 +60,14 @@ export function defineCapabilityCatalog(definitions, options = {}) {
             tools.push(tool);
         }
     }
-    validateToolReferences(owners.keys(), modules.flatMap(module => options.toolReferences ? synchronous(options.toolReferences(module), 'Capability reference projections must be synchronous') : []));
+    validateToolReferences(owners.keys(), modules.flatMap((module) => options.toolReferences
+        ? synchronous(options.toolReferences(module), 'Capability reference projections must be synchronous')
+        : []));
     return Object.freeze({
-        ...catalog, tools: Object.freeze(tools),
-        findToolOwner(toolId) { return owners.get(toolId); },
+        ...catalog,
+        tools: Object.freeze(tools),
+        findToolOwner(toolId) {
+            return owners.get(toolId);
+        },
     });
 }

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

@@ -1,9 +1,40 @@
 import type { ContextFragment } from '../../structs/context/fragments.js';
 import type { ContextBuilder, ContextBuilderOptions, ContextFragmentConfig, ContextAssemblyOptions, ContextProjection } from '../../structs/support/context.js';
-/** Compile context ordering once; expansion and formatting use each request's current input. */
+/**
+ * Compile ordered context projections into a builder.
+ *
+ * A projection is either a single fragment (with its own formatter) or a placement whose
+ * contribution handler expands to any number of fragments at request time.
+ *
+ * @param definitions Projections in the order they should appear in the plan.
+ * @param options Fragment factory, contribution handlers and an optional size budget.
+ * @returns A frozen builder exposing `fragments`, `plan` and `build`.
+ * @throws {Error} When a projection ID repeats, a formatter is missing, a placement has no
+ *   contribution handler, or a callback is asynchronous.
+ */
 export declare function defineContextAssembly<Input, Id extends string = string, Placement extends string = string>(definitions: readonly ContextProjection<Input, Id, Placement>[], options: ContextAssemblyOptions<Input, Id, Placement>): ContextBuilder<Input>;
-/** Full-metadata catalogs use the same builder without a separate metadata reference catalog. */
+/**
+ * Compile self-describing fragment declarations into a builder.
+ *
+ * Each definition carries its own trust, lifetime and size metadata, so no separate metadata
+ * catalog is needed. The budget may be a constant or a function of the request input.
+ *
+ * @param definitions Fragment configurations in plan order.
+ * @param options Optional transform, budget selector and related builder settings.
+ * @returns A frozen builder exposing `fragments`, `plan` and `build`.
+ * @throws {Error} When a fragment ID repeats or a formatter is missing or asynchronous.
+ * @throws {TypeError} When `plan`/`build` is called with no configured or overridden budget.
+ */
 export declare function defineContextFragments<Input>(definitions: readonly ContextFragmentConfig<Input>[], options?: ContextBuilderOptions<Input>): ContextBuilder<Input>;
-/** Transform all outbound text, including nested receipt values, before measuring context budgets. */
+/**
+ * Apply a text transform to a fragment value, including strings nested inside objects.
+ *
+ * Structured values are walked through a JSON round trip, which is what the budget measurement
+ * serializes later; values that JSON cannot represent are therefore not preserved.
+ *
+ * @param fragment Fragment whose value should be transformed.
+ * @param transform Pure text mapping applied to every string in the value.
+ * @returns A new fragment with unchanged metadata and the transformed value.
+ */
 export declare function transformContextText(fragment: ContextFragment, transform: (text: string) => string): ContextFragment;
-export type { ContextBuilder, ContextBuilderOptions, ContextFragmentConfig, ContextAssemblyOptions, ContextProjection } from '../../structs/support/context.js';
+export type { ContextBuilder, ContextBuilderOptions, ContextFragmentConfig, ContextAssemblyOptions, ContextProjection, } from '../../structs/support/context.js';

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

@@ -1,12 +1,34 @@
+/**
+ * Context builders: compile application fragment declarations into a Core `ContextBuilder`.
+ *
+ * Ordering and metadata are compiled once; fragment values and formatting are produced per
+ * request, so a builder may be shared across invocations. The builder only assembles a plan or
+ * built context; reduction, selection and model execution stay with Core or explicit nodes.
+ *
+ * Main exports: `defineContextAssembly`, `defineContextFragments` and `transformContextText`.
+ */
 import { synchronous } from '../../utils/synchronous.js';
 import { breakWhile } from '../../utils/rules.js';
 import { assembleContextPlan } from '../../context/plan.js';
 import { validateContextBudget } from '../../context/fragments.js';
-/** Compile context ordering once; expansion and formatting use each request's current input. */
+/**
+ * Compile ordered context projections into a builder.
+ *
+ * A projection is either a single fragment (with its own formatter) or a placement whose
+ * contribution handler expands to any number of fragments at request time.
+ *
+ * @param definitions Projections in the order they should appear in the plan.
+ * @param options Fragment factory, contribution handlers and an optional size budget.
+ * @returns A frozen builder exposing `fragments`, `plan` and `build`.
+ * @throws {Error} When a projection ID repeats, a formatter is missing, a placement has no
+ *   contribution handler, or a callback is asynchronous.
+ */
 export function defineContextAssembly(definitions, options) {
     const fragment = options.fragment.bind(options);
     const ids = new Set();
-    const factories = definitions.map(definition => {
+    const factories = definitions.map((definition) => {
+        // Contribution placements live in the same ID namespace, prefixed so they cannot collide with
+        // a real fragment ID.
         const id = definition.kind === 'fragment' ? definition.id : `contributions:${definition.placement}`;
         breakWhile(ids.has(id), `Duplicate context projection: ${id}`);
         ids.add(id);
@@ -14,7 +36,9 @@ export function defineContextAssembly(definitions, options) {
             const id = definition.id;
             breakWhile(typeof definition.format !== 'function', `Missing context formatter: ${id}`);
             const format = definition.format.bind(definition);
-            return (input) => [synchronous(fragment(id, synchronous(format(input), 'Context formatters must be synchronous')), 'Context fragment factories must be synchronous')];
+            return (input) => [
+                synchronous(fragment(id, synchronous(format(input), 'Context formatters must be synchronous')), 'Context fragment factories must be synchronous'),
+            ];
         }
         const create = options.contributions?.[definition.placement];
         breakWhile(typeof create !== 'function', `Unknown context contribution: ${definition.placement}`);
@@ -23,26 +47,52 @@ export function defineContextAssembly(definitions, options) {
     });
     return contextBuilder(factories, options);
 }
-/** Full-metadata catalogs use the same builder without a separate metadata reference catalog. */
+/**
+ * Compile self-describing fragment declarations into a builder.
+ *
+ * Each definition carries its own trust, lifetime and size metadata, so no separate metadata
+ * catalog is needed. The budget may be a constant or a function of the request input.
+ *
+ * @param definitions Fragment configurations in plan order.
+ * @param options Optional transform, budget selector and related builder settings.
+ * @returns A frozen builder exposing `fragments`, `plan` and `build`.
+ * @throws {Error} When a fragment ID repeats or a formatter is missing or asynchronous.
+ * @throws {TypeError} When `plan`/`build` is called with no configured or overridden budget.
+ */
 export function defineContextFragments(definitions, options = {}) {
     const ids = new Set();
-    const factories = definitions.map(definition => {
-        const metadata = { id: definition.id, sourceId: definition.sourceId, trust: definition.trust, lifetime: definition.lifetime, maxChars: definition.maxChars, role: definition.role };
+    const factories = definitions.map((definition) => {
+        const metadata = {
+            id: definition.id,
+            sourceId: definition.sourceId,
+            trust: definition.trust,
+            lifetime: definition.lifetime,
+            maxChars: definition.maxChars,
+            role: definition.role,
+        };
         breakWhile(typeof definition.format !== 'function', `Missing context formatter: ${metadata.id}`);
         const format = definition.format.bind(definition);
         breakWhile(ids.has(metadata.id), `Duplicate context fragment: ${metadata.id}`);
         ids.add(metadata.id);
-        return (input) => [{ ...metadata, value: synchronous(format(input), 'Context formatters must be synchronous') }];
+        return (input) => [
+            { ...metadata, value: synchronous(format(input), 'Context formatters must be synchronous') },
+        ];
     });
     return contextBuilder(factories, options);
 }
 function contextBuilder(factories, options) {
     const transform = options.transform?.bind(options);
     const configuredLimit = typeof options.maxInputChars === 'function'
-        ? options.maxInputChars.bind(options) : options.maxInputChars;
-    const fragments = (input) => factories.flatMap(create => create(input).map(value => transform ? synchronous(transform(value, input), 'Context transforms must be synchronous') : value));
+        ? options.maxInputChars.bind(options)
+        : options.maxInputChars;
+    const fragments = (input) => factories.flatMap((create) => create(input).map((value) => transform
+        ? synchronous(transform(value, input), 'Context transforms must be synchronous')
+        : value));
     function limit(input, override) {
-        const value = override ?? (typeof configuredLimit === 'function' ? synchronous(configuredLimit(input), 'Context budget selectors must be synchronous') : configuredLimit);
+        const value = override ??
+            (typeof configuredLimit === 'function'
+                ? synchronous(configuredLimit(input), 'Context budget selectors must be synchronous')
+                : configuredLimit);
         if (value === undefined)
             throw new TypeError('Configure a context budget or pass maxInputChars');
         validateContextBudget(0, value);
@@ -50,19 +100,41 @@ function contextBuilder(factories, options) {
     }
     return Object.freeze({
         fragments,
-        plan({ input, maxInputChars, originalFragments, additionalMessages, mutableFragmentIds }) {
+        plan({ input, maxInputChars, originalFragments, additionalMessages, mutableFragmentIds, }) {
             const budget = limit(input, maxInputChars);
-            return { fragments: fragments(input), maxInputChars: budget, originalFragments, additionalMessages, mutableFragmentIds };
+            return {
+                fragments: fragments(input),
+                maxInputChars: budget,
+                originalFragments,
+                additionalMessages,
+                mutableFragmentIds,
+            };
         },
-        build({ input, maxInputChars, originalFragments, additionalMessages, mutableFragmentIds }) {
+        build({ input, maxInputChars, originalFragments, additionalMessages, mutableFragmentIds, }) {
             const budget = limit(input, maxInputChars);
-            return assembleContextPlan({ fragments: fragments(input), maxInputChars: budget, originalFragments, additionalMessages, mutableFragmentIds });
+            return assembleContextPlan({
+                fragments: fragments(input),
+                maxInputChars: budget,
+                originalFragments,
+                additionalMessages,
+                mutableFragmentIds,
+            });
         },
     });
 }
-/** Transform all outbound text, including nested receipt values, before measuring context budgets. */
+/**
+ * Apply a text transform to a fragment value, including strings nested inside objects.
+ *
+ * Structured values are walked through a JSON round trip, which is what the budget measurement
+ * serializes later; values that JSON cannot represent are therefore not preserved.
+ *
+ * @param fragment Fragment whose value should be transformed.
+ * @param transform Pure text mapping applied to every string in the value.
+ * @returns A new fragment with unchanged metadata and the transformed value.
+ */
 export function transformContextText(fragment, transform) {
-    const value = typeof fragment.value === 'string' ? transform(fragment.value)
+    const value = typeof fragment.value === 'string'
+        ? transform(fragment.value)
         : JSON.parse(JSON.stringify(fragment.value, (_key, value) => typeof value === 'string' ? transform(value) : value));
     return { ...fragment, value };
 }

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

@@ -1,6 +1,22 @@
 import type { ContextCompressor } from '../../structs/support/context-processing.js';
 import type { ContextFragment } from '../../structs/context/fragments.js';
-/** Prompt and output contract belong to App; model execution stays on the Core call port. */
+/**
+ * Build a compressor that asks a model to rewrite one fragment.
+ *
+ * The request pairs a system instruction with a user message carrying the fragment ID, its current
+ * value and the target character count. Only the model's parsed value is returned; the caller
+ * decides whether the result fits the reduction contract.
+ *
+ * @param options Compressor declaration.
+ * @param options.id Handler ID referenced by `compress` reduction steps; must be unique per policy.
+ * @param options.instruction System prompt describing the compression task and output format.
+ * @param options.modelId Optional model override; defaults to the stage's prepared model.
+ * @param options.transport Registered transport ID used for the compression call.
+ * @param options.maxOutputTokens Output reservation for the compression call.
+ * @param options.parse Converts the model value into the fragment value type; must be synchronous.
+ * @returns A frozen `ContextCompressor` whose `compress` performs the model call.
+ * @throws {Error} When `parse` is not a function, or when the parser returns a thenable.
+ */
 export declare function createContextCompressor(options: {
     id: string;
     instruction: string;

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

@@ -1,15 +1,57 @@
+/**
+ * Context compressor factory: one model-backed compression handler for context reductions.
+ *
+ * The application owns the prompt and the output contract; the actual model call goes through the
+ * Core call port supplied with each compression request, so budgets, cancellation and diagnostics
+ * stay under Core control.
+ *
+ * Main export: `createContextCompressor`.
+ */
 import { breakWhile } from '../../utils/rules.js';
 import { synchronous } from '../../utils/synchronous.js';
-/** Prompt and output contract belong to App; model execution stays on the Core call port. */
+/**
+ * Build a compressor that asks a model to rewrite one fragment.
+ *
+ * The request pairs a system instruction with a user message carrying the fragment ID, its current
+ * value and the target character count. Only the model's parsed value is returned; the caller
+ * decides whether the result fits the reduction contract.
+ *
+ * @param options Compressor declaration.
+ * @param options.id Handler ID referenced by `compress` reduction steps; must be unique per policy.
+ * @param options.instruction System prompt describing the compression task and output format.
+ * @param options.modelId Optional model override; defaults to the stage's prepared model.
+ * @param options.transport Registered transport ID used for the compression call.
+ * @param options.maxOutputTokens Output reservation for the compression call.
+ * @param options.parse Converts the model value into the fragment value type; must be synchronous.
+ * @returns A frozen `ContextCompressor` whose `compress` performs the model call.
+ * @throws {Error} When `parse` is not a function, or when the parser returns a thenable.
+ */
 export function createContextCompressor(options) {
     const { id, instruction, modelId, transport, maxOutputTokens } = options;
     breakWhile(typeof options.parse !== 'function', 'Context compressor requires a result parser');
     const parse = options.parse.bind(options);
-    return Object.freeze({ id, async compress(call) {
-            const result = await call.callModel({ stageId: `${call.stageId}:compress:${id}`, modelId, input: [
+    return Object.freeze({
+        id,
+        async compress(call) {
+            const result = await call.callModel({
+                // Suffix the stage ID so compressor calls are attributable in diagnostics and budgets.
+                stageId: `${call.stageId}:compress:${id}`,
+                modelId,
+                input: [
                     { role: 'system', content: instruction },
-                    { role: 'user', content: JSON.stringify({ sourceId: call.fragment.sourceId, value: call.fragment.value, targetChars: call.targetChars }) },
-                ], maxOutputTokens, transport });
+                    {
+                        role: 'user',
+                        content: JSON.stringify({
+                            sourceId: call.fragment.sourceId,
+                            value: call.fragment.value,
+                            targetChars: call.targetChars,
+                        }),
+                    },
+                ],
+                maxOutputTokens,
+                transport,
+            });
             return synchronous(parse(result.value), 'Context result parsers must be synchronous');
-        } });
+        },
+    });
 }

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

@@ -1 +1,7 @@
+/**
+ * Re-export barrel: Core fragment assembly helpers used by context support code.
+ *
+ * Kept as a stable Support path so applications do not import Core internals directly. No logic
+ * lives here.
+ */
 export * from '../../context/assembly.js';

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

@@ -1 +1,7 @@
+/**
+ * Re-export barrel: Core fragment assembly helpers used by context support code.
+ *
+ * Kept as a stable Support path so applications do not import Core internals directly. No logic
+ * lives here.
+ */
 export * from '../../context/assembly.js';