@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/support/capabilities.js

@@ -2,10 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateToolReferences = validateToolReferences;
 exports.defineCapabilityCatalog = defineCapabilityCatalog;
+/**
+ * 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`.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const catalog_js_1 = require("../utils/catalog.js");
 const rules_js_1 = require("../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.
+ */
 function validateToolReferences(names, references) {
     const available = new Set(names);
     for (const reference of references) {
@@ -17,9 +37,21 @@ 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.
+ */
 function defineCapabilityCatalog(definitions, options = {}) {
-    const catalog = (0, catalog_js_1.readonlyCatalog)(definitions, id => new TypeError(`Unknown capability module: ${id}`));
+    const catalog = (0, catalog_js_1.readonlyCatalog)(definitions, (id) => new TypeError(`Unknown capability module: ${id}`));
     const modules = catalog.definitions;
     const owners = new Map();
     const tools = [];
@@ -32,9 +64,14 @@ function defineCapabilityCatalog(definitions, options = {}) {
             tools.push(tool);
         }
     }
-    validateToolReferences(owners.keys(), modules.flatMap(module => options.toolReferences ? (0, synchronous_js_1.synchronous)(options.toolReferences(module), 'Capability reference projections must be synchronous') : []));
+    validateToolReferences(owners.keys(), modules.flatMap((module) => options.toolReferences
+        ? (0, synchronous_js_1.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/cjs/support/context/assembly.js

@@ -3,15 +3,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineContextAssembly = defineContextAssembly;
 exports.defineContextFragments = defineContextFragments;
 exports.transformContextText = transformContextText;
+/**
+ * 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`.
+ */
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const rules_js_1 = require("../../utils/rules.js");
 const plan_js_1 = require("../../context/plan.js");
 const fragments_js_1 = require("../../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.
+ */
 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}`;
         (0, rules_js_1.breakWhile)(ids.has(id), `Duplicate context projection: ${id}`);
         ids.add(id);
@@ -19,7 +41,9 @@ function defineContextAssembly(definitions, options) {
             const id = definition.id;
             (0, rules_js_1.breakWhile)(typeof definition.format !== 'function', `Missing context formatter: ${id}`);
             const format = definition.format.bind(definition);
-            return (input) => [(0, synchronous_js_1.synchronous)(fragment(id, (0, synchronous_js_1.synchronous)(format(input), 'Context formatters must be synchronous')), 'Context fragment factories must be synchronous')];
+            return (input) => [
+                (0, synchronous_js_1.synchronous)(fragment(id, (0, synchronous_js_1.synchronous)(format(input), 'Context formatters must be synchronous')), 'Context fragment factories must be synchronous'),
+            ];
         }
         const create = options.contributions?.[definition.placement];
         (0, rules_js_1.breakWhile)(typeof create !== 'function', `Unknown context contribution: ${definition.placement}`);
@@ -28,26 +52,52 @@ 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.
+ */
 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,
+        };
         (0, rules_js_1.breakWhile)(typeof definition.format !== 'function', `Missing context formatter: ${metadata.id}`);
         const format = definition.format.bind(definition);
         (0, rules_js_1.breakWhile)(ids.has(metadata.id), `Duplicate context fragment: ${metadata.id}`);
         ids.add(metadata.id);
-        return (input) => [{ ...metadata, value: (0, synchronous_js_1.synchronous)(format(input), 'Context formatters must be synchronous') }];
+        return (input) => [
+            { ...metadata, value: (0, synchronous_js_1.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 ? (0, synchronous_js_1.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
+        ? (0, synchronous_js_1.synchronous)(transform(value, input), 'Context transforms must be synchronous')
+        : value));
     function limit(input, override) {
-        const value = override ?? (typeof configuredLimit === 'function' ? (0, synchronous_js_1.synchronous)(configuredLimit(input), 'Context budget selectors must be synchronous') : configuredLimit);
+        const value = override ??
+            (typeof configuredLimit === 'function'
+                ? (0, synchronous_js_1.synchronous)(configuredLimit(input), 'Context budget selectors must be synchronous')
+                : configuredLimit);
         if (value === undefined)
             throw new TypeError('Configure a context budget or pass maxInputChars');
         (0, fragments_js_1.validateContextBudget)(0, value);
@@ -55,19 +105,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 (0, plan_js_1.assembleContextPlan)({ fragments: fragments(input), maxInputChars: budget, originalFragments, additionalMessages, mutableFragmentIds });
+            return (0, plan_js_1.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.
+ */
 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/cjs/support/context/compression.js

@@ -1,18 +1,60 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createContextCompressor = createContextCompressor;
+/**
+ * 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`.
+ */
 const rules_js_1 = require("../../utils/rules.js");
 const synchronous_js_1 = require("../../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.
+ */
 function createContextCompressor(options) {
     const { id, instruction, modelId, transport, maxOutputTokens } = options;
     (0, rules_js_1.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 (0, synchronous_js_1.synchronous)(parse(result.value), 'Context result parsers must be synchronous');
-        } });
+        },
+    });
 }

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

@@ -14,4 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.
+ */
 __exportStar(require("../../context/assembly.js"), exports);

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

@@ -8,6 +8,14 @@ const errors_js_1 = require("../../structs/errors.js");
 const rules_js_1 = require("../../utils/rules.js");
 const invalid = (message) => new errors_js_1.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.
+ */
 function historyGrouping(options) {
     const grouping = options.grouping;
     (0, rules_js_1.breakWhile)(!grouping || !Object.hasOwn(exports.historyGroupingCatalog, grouping.kind), invalid('Unknown history grouping'));
@@ -30,7 +38,9 @@ function userTurns(entries) {
     const groups = [];
     for (const entry of entries) {
         const message = entry;
-        (0, rules_js_1.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'));
+        (0, rules_js_1.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([]);
         (0, rules_js_1.breakWhile)(!groups.length, invalid('User-turn history cannot start with an orphan assistant message'));
@@ -38,15 +48,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.
+ */
 exports.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.
+ */
 function historyGroups(value, options) {
     (0, rules_js_1.breakWhile)(typeof value === 'string' || !Array.isArray(value[options.field]), invalid('History requires a structured array field'));
     const grouping = historyGrouping(options);
     return exports.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.
+ */
 function validateRecentHistory(options) {
     (0, rules_js_1.breakWhile)(!options.field || !Number.isSafeInteger(options.keepGroups) || options.keepGroups < 0, invalid('Invalid recent-history retention'));
     historyGrouping(options);

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

@@ -15,6 +15,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contextHistoryStrategies = exports.createContextStrategy = exports.contextReductionCatalog = exports.contextPolicyCatalog = exports.validateContextPolicy = exports.processContext = void 0;
+/**
+ * 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.
+ */
 __exportStar(require("./assembly.js"), exports);
 __exportStar(require("./fragments.js"), exports);
 __exportStar(require("./compression.js"), exports);