@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/kits/projection.js

@@ -4,22 +4,45 @@ exports.Projection = void 0;
 exports.defineContentProjection = defineContentProjection;
 exports.projectContinuousExcerpt = projectContinuousExcerpt;
 exports.defineTreeProjection = defineTreeProjection;
+/**
+ * Projection Kit: fit structured values into a character budget without losing valid JSON.
+ *
+ * Place in the package: an optional App-side helper for context and preview budgets. Callers
+ * choose the budget, the rendering strategy and the fallback text; this module only shrinks
+ * values and verifies the result still fits.
+ *
+ * Exports: `defineContentProjection`, `projectContinuousExcerpt`, `defineTreeProjection`,
+ * `Projection`, and the projection option/result types.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const fragments_js_1 = require("../context/fragments.js");
-/** Keep valid JSON while reducing prose before dropping records; budgets are caller policy. */
+/**
+ * Compile a JSON-preserving projector.
+ *
+ * Keep valid JSON while reducing prose before dropping records; budgets are caller policy.
+ * The candidate list is tried in order (outer `counts`, inner `lengths`), so callers control
+ * whether trimming text or dropping items is preferred, and the configured fallback is used
+ * only when no candidate fits.
+ *
+ * @param options - Candidate bounds, a synchronous renderer and a synchronous fallback factory.
+ * @returns A frozen object whose `project({ value, maxChars })` returns `{ text, truncated }`.
+ * @throws TypeError For a negative or non-integer `maxChars`, or a non-synchronous renderer;
+ *   a `CONTEXT_BUDGET` `ValidationError` from the budget check when even the fallback is long.
+ */
 function defineContentProjection(options) {
     const counts = [...options.counts], lengths = [...options.lengths];
     const render = options.render.bind(options), fallback = options.fallback.bind(options);
     function shorten(value, length, count) {
+        // The ellipsis is explicit so a reader can tell truncated text from original text.
         if (typeof value === 'string')
             return value.length <= length ? value : value.slice(0, length) + '…';
         if (Array.isArray(value))
-            return value.slice(0, count).map(child => shorten(child, length, count));
+            return value.slice(0, count).map((child) => shorten(child, length, count));
         if (value && typeof value === 'object')
             return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, shorten(child, length, count)]));
         return value;
     }
-    function project({ value, maxChars: limit }) {
+    function project({ value, maxChars: limit, }) {
         if (!Number.isSafeInteger(limit) || limit < 0)
             throw new TypeError('Invalid projection maxChars');
         const original = JSON.stringify(value);
@@ -37,7 +60,19 @@ function defineContentProjection(options) {
     }
     return Object.freeze({ project });
 }
-/** Binary-search a continuous prefix and keep an existing surrogate pair intact. */
+/**
+ * Project a continuous excerpt of a body by binary-searching the longest prefix that fits.
+ *
+ * Binary-search a continuous prefix and keep an existing surrogate pair intact. `render`
+ * receives the prefix length, not the text, so the caller decides how the excerpt is framed.
+ *
+ * @param body - Source text whose length bounds the search.
+ * @param limit - Maximum rendered length in characters.
+ * @param render - Synchronous renderer for a given prefix length.
+ * @returns The fitting projection, or `undefined` when even the empty excerpt does not fit.
+ * @throws TypeError For an invalid limit or a non-synchronous renderer; a `CONTEXT_BUDGET`
+ *   `ValidationError` when the chosen excerpt still exceeds the budget.
+ */
 function projectContinuousExcerpt(body, limit, render) {
     (0, fragments_js_1.validateContextBudget)(0, limit);
     const excerpt = (length) => (0, synchronous_js_1.synchronous)(render(length), 'Excerpt renderers must be synchronous');
@@ -57,7 +92,19 @@ function projectContinuousExcerpt(body, limit, render) {
     (0, fragments_js_1.validateContextBudget)(text.length, limit);
     return { text, truncated: true };
 }
-/** Traverse synchronously in property/array order; only undefined omits a result. */
+/**
+ * Compile a depth-limited tree transform.
+ *
+ * Traverse synchronously in property/array order; only undefined omits a result. Because a
+ * visitor returns a new value instead of mutating, an omitted branch disappears from arrays
+ * and objects the same way, and `maxDepth` bounds both cycles and cost.
+ *
+ * @param options - Maximum depth (0 keeps only the root), optional omit predicate and optional
+ *   record visitor.
+ * @returns A frozen object whose `visit(value, context)` returns the projected value.
+ * @throws TypeError For a negative or non-integer `maxDepth`; a predicate that is not
+ *   synchronous boolean; a visitor that returns a thenable.
+ */
 function defineTreeProjection(options) {
     const { maxDepth } = options, omit = options.omit?.bind(options), visitRecord = options.visitRecord?.bind(options);
     if (!Number.isSafeInteger(maxDepth) || maxDepth < 0)
@@ -65,10 +112,13 @@ function defineTreeProjection(options) {
     function visit(value, depth, context) {
         if (depth > maxDepth)
             return undefined;
-        if (omit && (0, synchronous_js_1.booleanResult)(omit(value, depth, context), 'Tree omit predicates must return boolean synchronously'))
+        if (omit &&
+            (0, synchronous_js_1.booleanResult)(omit(value, depth, context), 'Tree omit predicates must return boolean synchronously'))
             return undefined;
         if (Array.isArray(value))
-            return value.map(item => visit(item, depth + 1, context)).filter(item => item !== undefined);
+            return value
+                .map((item) => visit(item, depth + 1, context))
+                .filter((item) => item !== undefined);
         if (value === null || typeof value !== 'object')
             return value;
         const record = value;
@@ -81,4 +131,9 @@ function defineTreeProjection(options) {
     const project = (value, context) => visit(value, 0, context);
     return Object.freeze({ visit: project });
 }
-exports.Projection = Object.freeze({ defineContentProjection, projectContinuousExcerpt, defineTreeProjection });
+/** Namespace object for callers that prefer one import over named helpers. */
+exports.Projection = Object.freeze({
+    defineContentProjection,
+    projectContinuousExcerpt,
+    defineTreeProjection,
+});

package/dist/cjs/kits/rank-fusion.js

@@ -1,23 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reciprocalRankFusion = reciprocalRankFusion;
+/**
+ * Reciprocal rank fusion for several ranked id lists.
+ *
+ * Place in the package: an optional App-side helper for merging retrieval or search results.
+ * Only ranks are combined, never raw scores, so lists produced by incomparable scorers stay
+ * comparable. Storage and source selection belong to the App.
+ *
+ * Exports: `reciprocalRankFusion`, `RankedList`, `FusedRank`.
+ */
 const rules_js_1 = require("../utils/rules.js");
-/** One-based reciprocal rank fusion. Raw retriever scores are intentionally not mixed. */
+/**
+ * Fuse ranked lists with one-based reciprocal rank fusion.
+ *
+ * Raw retriever scores are intentionally not mixed. Ties break on id, so the output is
+ * deterministic for a given input.
+ *
+ * @param lists - Ranked lists with unique source ids and positive weights.
+ * @param options - `limit` is the maximum number of fused results (1..1000); `k` smooths the
+ *   contribution of the top ranks and defaults to the conventional value 60.
+ * @returns At most `limit` fused ranks, best first.
+ * @throws A configured error for invalid options, a duplicate/blank source id, non-string ids,
+ *   or a non-positive weight.
+ */
 function reciprocalRankFusion(lists, options) {
+    // 60 is the smoothing constant popularised by the original RRF paper and keeps rank
+    // differences meaningful without letting the top hit dominate.
     const k = options.k ?? 60, sources = new Set(), candidates = new Map();
     (0, rules_js_1.breakWhile)(!Number.isFinite(k) ||
         k < 0 ||
         !Number.isSafeInteger(options.limit) ||
         options.limit < 1 ||
-        options.limit > 1000, "Invalid RRF options");
+        options.limit > 1000, 'Invalid RRF options');
     for (const list of lists) {
         const weight = list.weight ?? 1, sourceId = list.sourceId;
         (0, rules_js_1.breakWhile)(!sourceId?.trim() ||
             sources.has(sourceId) ||
             !Array.isArray(list.ids) ||
-            list.ids.some((id) => typeof id !== "string" || !id.trim()) ||
+            list.ids.some((id) => typeof id !== 'string' || !id.trim()) ||
             !Number.isFinite(weight) ||
-            weight <= 0, "Invalid ranked source");
+            weight <= 0, 'Invalid ranked source');
         sources.add(sourceId);
         const seen = new Set();
         for (const id of list.ids) {

package/dist/cjs/kits/reflection-log-source.js

@@ -1,37 +1,87 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineReflectionLogSource = defineReflectionLogSource;
+/**
+ * Reflection Kit: adapt an App-owned execution log reader into an authorized reflection source.
+ *
+ * Place in the package: part of the `reflection` Kit. It projects metadata only — no payloads,
+ * text, file paths or replay — and remembers which runs a caller discovered, so a guessed run
+ * cannot be read in a later call.
+ *
+ * Exports: `defineReflectionLogSource`, `ReflectionLogReader`.
+ */
 const rules_js_1 = require("../utils/rules.js");
 const reflection_js_1 = require("../structs/kits/reflection.js");
 const cancellation_js_1 = require("../utils/cancellation.js");
-const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
 const eventMetrics = {
     'model.end': (payload) => object(payload.state),
     'workflow.event': (payload) => object(payload.event),
 };
 const workflowStatuses = {
-    enter: 'running', transition: 'running', continue: 'running', complete: 'success', error: 'error',
+    enter: 'running',
+    transition: 'running',
+    continue: 'running',
+    complete: 'success',
+    error: 'error',
 };
 const cancellationCodes = new Set(['CANCELLED', 'TIMEOUT', 'CALL_TIMEOUT', 'ROUND_TIMEOUT']);
+/**
+ * Build a reflection source over a log reader.
+ *
+ * Coverage is reported as `best-effort`: a page is only `complete` when the reader exhausted the
+ * run without capture gaps or omitted issues, and every gap or issue code is surfaced instead of
+ * being silently dropped.
+ *
+ * @param options - Reader, source id, optional fixed trace id and the authorization hook.
+ * @returns A frozen source whose `query` returns reflection evidence.
+ * @throws A configured or authorization error for a malformed page, an expired run or event, or
+ *   a run that this source has not discovered yet; `TypeError` when authorization returns a value.
+ */
 function defineReflectionLogSource(options) {
     const reader = options.reader, traceId = options.traceId, authorize = options.authorize.bind(options), allowed = new Map();
     const checkAuthorization = (context) => (0, cancellation_js_1.awaitAssertion)(() => authorize(context), context.signal, 'Reflection log authorization must return void');
-    const coverage = (page) => ({ consistency: 'best-effort',
-        complete: page.coverage.exhausted && !page.coverage.captureIncomplete && !page.issues.length && !page.issuesOmitted,
-        gaps: [...new Set([...(page.status === 'end' ? [] : [page.status]), ...page.issues.map(item => item.code),
-                ...(page.issuesOmitted ? ['issues omitted'] : []), ...(page.coverage.captureIncomplete ? ['capture incomplete'] : [])])].slice(0, 32) });
-    return Object.freeze({ id: options.id, description: 'Explicitly authorized execution metadata; no payloads, text, file paths or replay.',
+    const coverage = (page) => ({
+        consistency: 'best-effort',
+        complete: page.coverage.exhausted &&
+            !page.coverage.captureIncomplete &&
+            !page.issues.length &&
+            !page.issuesOmitted,
+        gaps: [
+            ...new Set([
+                ...(page.status === 'end' ? [] : [page.status]),
+                ...page.issues.map((item) => item.code),
+                ...(page.issuesOmitted ? ['issues omitted'] : []),
+                ...(page.coverage.captureIncomplete ? ['capture incomplete'] : []),
+            ]),
+        ].slice(0, 32),
+    });
+    return Object.freeze({
+        id: options.id,
+        description: 'Explicitly authorized execution metadata; no payloads, text, file paths or replay.',
         authorize: (_query, context) => checkAuthorization(context),
         async query(query, context) {
             await checkAuthorization(context);
             if (!query.run) {
-                const page = await (0, cancellation_js_1.awaitWithSignal)(reader.listRuns({ traceId, cursor: query.cursor, limit: query.limit, signal: context.signal }), context.signal);
+                const page = await (0, cancellation_js_1.awaitWithSignal)(reader.listRuns({
+                    traceId,
+                    cursor: query.cursor,
+                    limit: query.limit,
+                    signal: context.signal,
+                }), context.signal);
                 context.signal.throwIfAborted();
                 const items = page.items.map(({ path, manifest }) => {
                     const expiresAtMs = Number(manifest.expiresAt);
                     (0, rules_js_1.breakWhile)(!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now(), 'Log evidence expired');
-                    return { id: `run:${String(manifest.runId)}`, runId: path, type: 'run', expiresAtMs,
-                        ...(typeof manifest.outcome === 'string' ? { status: manifest.outcome } : {}) };
+                    return {
+                        id: `run:${String(manifest.runId)}`,
+                        runId: path,
+                        type: 'run',
+                        expiresAtMs,
+                        ...(typeof manifest.outcome === 'string' ? { status: manifest.outcome } : {}),
+                    };
                 });
                 const result = { items, cursor: page.cursor, coverage: coverage(page) };
                 context.signal.throwIfAborted();
@@ -42,14 +92,29 @@ function defineReflectionLogSource(options) {
             }
             const expiresAtMs = allowed.get(query.run);
             (0, rules_js_1.breakWhile)(!expiresAtMs || expiresAtMs <= Date.now(), 'Run was not discovered in this authorized review');
-            const page = await (0, cancellation_js_1.awaitWithSignal)(reader.readEvents({ run: query.run, sources: ['core'], types: query.types, cursor: query.cursor, limit: query.limit, signal: context.signal }), context.signal);
+            const page = await (0, cancellation_js_1.awaitWithSignal)(reader.readEvents({
+                run: query.run,
+                sources: ['core'],
+                types: query.types,
+                cursor: query.cursor,
+                limit: query.limit,
+                signal: context.signal,
+            }), context.signal);
             context.signal.throwIfAborted();
             (0, rules_js_1.breakWhile)(expiresAtMs <= Date.now(), 'Log evidence expired');
             const items = page.items.map((event) => {
                 const state = object(event.payload), type = String(event.type ?? event.event);
-                const select = Object.hasOwn(eventMetrics, type) ? eventMetrics[type] : undefined;
+                const select = Object.hasOwn(eventMetrics, type)
+                    ? eventMetrics[type]
+                    : undefined;
                 const metrics = select ? select(state) : state;
-                const item = { id: `${String(event.runId)}:${String(event.sequence)}`, runId: query.run, type: event.type ?? event.event, sequence: event.sequence, expiresAtMs };
+                const item = {
+                    id: `${String(event.runId)}:${String(event.sequence)}`,
+                    runId: query.run,
+                    type: event.type ?? event.event,
+                    sequence: event.sequence,
+                    expiresAtMs,
+                };
                 for (const key of reflection_js_1.reflectionIdentityFields)
                     if (typeof event[key] === 'string')
                         item[key] = event[key];
@@ -60,11 +125,19 @@ function defineReflectionLogSource(options) {
                     if (typeof value === 'string')
                         item[key] = value;
                 }
-                const code = metrics.errorCode ?? state.errorCode ?? (Array.isArray(metrics.codes) ? metrics.codes[0] : undefined) ?? object(metrics.error).code;
+                const code = metrics.errorCode ??
+                    state.errorCode ??
+                    (Array.isArray(metrics.codes) ? metrics.codes[0] : undefined) ??
+                    object(metrics.error).code;
                 if (typeof code === 'string')
                     item.code = code;
-                if ((type === 'workflow.event' || type === 'loop.event') && typeof metrics.type === 'string' && Object.hasOwn(workflowStatuses, metrics.type)) {
-                    item.status = metrics.type === 'error' && typeof code === 'string' && cancellationCodes.has(code) ? 'cancelled' : workflowStatuses[metrics.type];
+                if ((type === 'workflow.event' || type === 'loop.event') &&
+                    typeof metrics.type === 'string' &&
+                    Object.hasOwn(workflowStatuses, metrics.type)) {
+                    item.status =
+                        metrics.type === 'error' && typeof code === 'string' && cancellationCodes.has(code)
+                            ? 'cancelled'
+                            : workflowStatuses[metrics.type];
                 }
                 for (const key of ['durationMs', 'inputChars', 'outputChars', 'calls'])
                     if (typeof metrics[key] === 'number')