@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/kits/projection.js

@@ -1,19 +1,42 @@
+/**
+ * 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.
+ */
 import { booleanResult, synchronous } from '../utils/synchronous.js';
 import { validateContextBudget } from '../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.
+ */
 export 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);
@@ -31,7 +54,19 @@ export 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.
+ */
 export function projectContinuousExcerpt(body, limit, render) {
     validateContextBudget(0, limit);
     const excerpt = (length) => synchronous(render(length), 'Excerpt renderers must be synchronous');
@@ -51,7 +86,19 @@ export function projectContinuousExcerpt(body, limit, render) {
     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.
+ */
 export function defineTreeProjection(options) {
     const { maxDepth } = options, omit = options.omit?.bind(options), visitRecord = options.visitRecord?.bind(options);
     if (!Number.isSafeInteger(maxDepth) || maxDepth < 0)
@@ -59,10 +106,13 @@ export function defineTreeProjection(options) {
     function visit(value, depth, context) {
         if (depth > maxDepth)
             return undefined;
-        if (omit && booleanResult(omit(value, depth, context), 'Tree omit predicates must return boolean synchronously'))
+        if (omit &&
+            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;
@@ -75,4 +125,9 @@ export function defineTreeProjection(options) {
     const project = (value, context) => visit(value, 0, context);
     return Object.freeze({ visit: project });
 }
-export const Projection = Object.freeze({ defineContentProjection, projectContinuousExcerpt, defineTreeProjection });
+/** Namespace object for callers that prefer one import over named helpers. */
+export const Projection = Object.freeze({
+    defineContentProjection,
+    projectContinuousExcerpt,
+    defineTreeProjection,
+});

package/dist/esm/kits/rank-fusion.d.ts

@@ -1,18 +1,38 @@
+/** One retriever's ordered result, optionally weighted. */
 export interface RankedList {
+    /** Unique source name; duplicate names are rejected because they would double-count. */
     readonly sourceId: string;
+    /** Ids in descending relevance; duplicates inside one list are ignored after the first. */
     readonly ids: readonly string[];
+    /** Relative source weight, strictly positive; defaults to 1. */
     readonly weight?: number;
 }
+/** One fused result with the per-source ranks that produced its score. */
 export interface FusedRank {
+    /** Fused document id. */
     id: string;
+    /** Sum of `weight / (k + rank)` over contributing sources; higher is better. */
     score: number;
+    /** Contributions in source order, using one-based ranks. */
     contributions: {
         sourceId: string;
         rank: number;
         weight: number;
     }[];
 }
-/** 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.
+ */
 export declare function reciprocalRankFusion(lists: readonly RankedList[], options: {
     limit: number;
     k?: number;

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

@@ -1,20 +1,43 @@
-import { breakWhile } from "../utils/rules.js";
-/** One-based reciprocal rank fusion. Raw retriever scores are intentionally not mixed. */
+/**
+ * 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`.
+ */
+import { breakWhile } from '../utils/rules.js';
+/**
+ * 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.
+ */
 export 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();
     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;
         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/esm/kits/reflection-log-source.d.ts

@@ -13,8 +13,17 @@ interface Page<T> {
         captureIncomplete?: boolean;
     };
 }
-/** Structural port: the App supplies its own FileLogReader, trusted scope and current authorization. */
+/**
+ * Structural port: the App supplies its own FileLogReader, trusted scope and current
+ * authorization.
+ */
 export interface ReflectionLogReader {
+    /**
+     * List runs the caller may inspect.
+     *
+     * @param query - Optional trace filter, pagination cursor, page limit and abort signal.
+     * @returns A page of runs with their file path and manifest.
+     */
     listRuns(query: {
         traceId?: string;
         cursor?: string;
@@ -24,6 +33,12 @@ export interface ReflectionLogReader {
         path: string;
         manifest: Readonly<Record<string, unknown>>;
     }>>;
+    /**
+     * Read the events of one run.
+     *
+     * @param query - Run id, optional source/type filters, pagination cursor, limit and signal.
+     * @returns A page of raw event records.
+     */
     readEvents(query: {
         run: string;
         sources?: readonly ('app' | 'core' | 'client')[];
@@ -33,6 +48,18 @@ export interface ReflectionLogReader {
         signal?: AbortSignal;
     }): Promise<Page<Record<string, unknown>>>;
 }
+/**
+ * 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.
+ */
 export declare function defineReflectionLogSource<App>(options: {
     reader: ReflectionLogReader;
     id: string;

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

@@ -1,34 +1,84 @@
+/**
+ * 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`.
+ */
 import { breakWhile } from '../utils/rules.js';
 import { reflectionIdentityFields } from '../structs/kits/reflection.js';
 import { awaitAssertion, awaitWithSignal } from '../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.
+ */
 export function defineReflectionLogSource(options) {
     const reader = options.reader, traceId = options.traceId, authorize = options.authorize.bind(options), allowed = new Map();
     const checkAuthorization = (context) => 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 awaitWithSignal(reader.listRuns({ traceId, cursor: query.cursor, limit: query.limit, signal: context.signal }), context.signal);
+                const page = await 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);
                     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();
@@ -39,14 +89,29 @@ export function defineReflectionLogSource(options) {
             }
             const expiresAtMs = allowed.get(query.run);
             breakWhile(!expiresAtMs || expiresAtMs <= Date.now(), 'Run was not discovered in this authorized review');
-            const page = await 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 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();
             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 reflectionIdentityFields)
                     if (typeof event[key] === 'string')
                         item[key] = event[key];
@@ -57,11 +122,19 @@ export 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')

package/dist/esm/kits/reflection.d.ts

@@ -1,9 +1,25 @@
 import { type ReflectionDefinition, type ReflectionTask } from '../structs/kits/reflection.js';
-/** Model-driven investigation through ordinary registered tools and the existing Core loop. */
+/**
+ * Compile a reflection task.
+ *
+ * Model-driven investigation through ordinary registered tools and the existing Core loop. The
+ * task always reports `persisted: false`: storing a report is the App's decision. Observed
+ * findings must cite evidence ids that were actually returned in this run, which is what keeps
+ * the report tied to real observations instead of model recall.
+ *
+ * @param definition - Model child factory, authorized source, extra read-only tools and limits.
+ * @returns A frozen task whose `run(question, context)` returns a report.
+ * @throws TypeError For a non-read-only extra tool, invalid limits or an oversized question;
+ *   an authorization error from the App hook. Budget exhaustion returns an `incomplete` report
+ *   rather than throwing.
+ */
 export declare function defineReflection<App>(definition: ReflectionDefinition<App>): ReflectionTask<App>;
+/** Namespace object for callers that prefer one import over named helpers. */
 export declare const Reflection: Readonly<{
     defineReflection: typeof defineReflection;
 }>;
 export type * from '../structs/kits/reflection.js';
+/** Finding kinds and the identity fields copied into evidence metadata. */
 export { reflectionFindingKinds, reflectionIdentityFields } from '../structs/kits/reflection.js';
+/** Adapter that turns an App log reader into a reflection source. */
 export { defineReflectionLogSource, type ReflectionLogReader } from './reflection-log-source.js';