@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/kits/answering/flow.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineAnswerFlow = defineAnswerFlow;
+/**
+ * Answering Kit: the bounded generate → check → review → repair → deliver workflow.
+ *
+ * Place in the package: part of the `answering` Kit and the only module that composes the
+ * other answering pieces. Generation, checking, review, fallback and budget checks are App
+ * handlers; this module owns the stage graph, cell state, repair budget and result statuses.
+ *
+ * Exports: `defineAnswerFlow`, and the answer flow/item/result/check types.
+ */
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const cancellation_js_1 = require("../../utils/cancellation.js");
 const engine_js_1 = require("../../execution/engine.js");
@@ -9,13 +18,34 @@ const batch_js_1 = require("./batch.js");
 const check_result_js_1 = require("./check-result.js");
 const observer_js_1 = require("../../utils/observer.js");
 const unavailable = () => ({ status: 'unavailable', issues: [] });
-/** Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned. */
+/**
+ * Compile a reusable answer workflow.
+ *
+ * Reusable answer workflow. Requests own cells and repair budgets; models remain caller-owned.
+ * The flow runs at most `maxRepairs + 1` rounds: one generation pass, then one repair round per
+ * failing item set, and finally an explicit accepted/fallback/blocked result per item.
+ *
+ * @param definition - Batch limits, review policy, generation/check/review/fallback/canInvoke
+ *   handlers and an optional observer; handlers are bound to this object.
+ * @returns A frozen flow whose `run({ inputIds, items }, context)` returns one result per item.
+ * @throws TypeError At construction for invalid limits or policy, or a missing handler; from
+ *   `run` for an invalid batch, non-synchronous handlers, or generated/reviewed values that do
+ *   not belong to the requested items.
+ */
 function defineAnswerFlow(definition) {
     const { maxItems, maxRepairs } = definition, reviewPolicy = definition.reviewPolicy ?? 'optional';
-    if (!Number.isSafeInteger(maxItems) || maxItems < 1 || !Number.isSafeInteger(maxRepairs) || maxRepairs < 0
-        || !['optional', 'required', 'off'].includes(reviewPolicy))
+    if (!Number.isSafeInteger(maxItems) ||
+        maxItems < 1 ||
+        !Number.isSafeInteger(maxRepairs) ||
+        maxRepairs < 0 ||
+        !['optional', 'required', 'off'].includes(reviewPolicy))
         throw new TypeError('Invalid answer flow limits or policy');
-    for (const handler of [definition.generate, definition.check, definition.fallback, definition.canInvoke]) {
+    for (const handler of [
+        definition.generate,
+        definition.check,
+        definition.fallback,
+        definition.canInvoke,
+    ]) {
         if (typeof handler !== 'function')
             throw new TypeError('Missing answer flow handler');
     }
@@ -29,9 +59,15 @@ function defineAnswerFlow(definition) {
         return value;
     };
     const issues = (cell) => {
-        const result = [...cell.local.issues, ...(cell.review.status === 'failed' ? cell.review.issues : [])];
+        const result = [
+            ...cell.local.issues,
+            ...(cell.review.status === 'failed' ? cell.review.issues : []),
+        ];
         if (!cell.hasValue || cell.local.status !== 'passed')
-            result.push({ code: !cell.hasValue ? 'ANSWER_MISSING' : 'ANSWER_LOCAL_CHECK', message: 'No locally accepted value' });
+            result.push({
+                code: !cell.hasValue ? 'ANSWER_MISSING' : 'ANSWER_LOCAL_CHECK',
+                message: 'No locally accepted value',
+            });
         if ((reviewPolicy === 'required' || cell.knownReviewFailure) && cell.review.status !== 'passed')
             result.push({ code: 'ANSWER_REVIEW_REQUIRED', message: 'Required review is unresolved' });
         return result;
@@ -39,20 +75,26 @@ function defineAnswerFlow(definition) {
     function observe(stageId, cells, context) {
         if (!observer)
             return;
-        const results = cells.map(cell => ({ item: cell.item, value: cell.value, status: 'blocked', issues: issues(cell), checks: { local: cell.local, review: cell.review } }));
-        (0, observer_js_1.observeSafely)(input => observer(input, context), { stageId, results });
+        const results = cells.map((cell) => ({
+            item: cell.item,
+            value: cell.value,
+            status: 'blocked',
+            issues: issues(cell),
+            checks: { local: cell.local, review: cell.review },
+        }));
+        (0, observer_js_1.observeSafely)((input) => observer(input, context), { stageId, results });
     }
     async function generate(cells, repair, context) {
         context.signal.throwIfAborted();
         if (!cells.length || !allowed(context))
             return;
-        const previous = new Map(cells.flatMap(cell => !cell.hasValue ? [] : [[cell.item.id, cell.value]]));
-        const repairs = repair ? new Map(cells.map(cell => [cell.item.id, issues(cell)])) : undefined;
+        const previous = new Map(cells.flatMap((cell) => !cell.hasValue ? [] : [[cell.item.id, cell.value]]));
+        const repairs = repair ? new Map(cells.map((cell) => [cell.item.id, issues(cell)])) : undefined;
         for (const cell of cells)
             cell.generated = false;
         let values;
         try {
-            values = await (0, cancellation_js_1.awaitWithSignal)(generateValues({ items: cells.map(cell => cell.item), repairs, previous }, context), context.signal);
+            values = await (0, cancellation_js_1.awaitWithSignal)(generateValues({ items: cells.map((cell) => cell.item), repairs, previous }, context), context.signal);
         }
         catch {
             context.signal.throwIfAborted();
@@ -60,7 +102,10 @@ function defineAnswerFlow(definition) {
             return;
         }
         context.signal.throwIfAborted();
-        if (!values || typeof values.get !== 'function' || typeof values.keys !== 'function' || [...values.keys()].some(id => !cells.some(cell => cell.item.id === id)))
+        if (!values ||
+            typeof values.get !== 'function' ||
+            typeof values.keys !== 'function' ||
+            [...values.keys()].some((id) => !cells.some((cell) => cell.item.id === id)))
             throw new TypeError('Invalid generated answer ownership');
         for (const cell of cells) {
             cell.hasValue = values.has(cell.item.id);
@@ -86,7 +131,7 @@ function defineAnswerFlow(definition) {
     }
     async function review(cells, context) {
         context.signal.throwIfAborted();
-        const selected = cells.filter(cell => cell.local.status === 'passed' && cell.hasValue);
+        const selected = cells.filter((cell) => cell.local.status === 'passed' && cell.hasValue);
         if (!selected.length)
             return;
         if (reviewPolicy === 'off') {
@@ -101,7 +146,7 @@ function defineAnswerFlow(definition) {
         }
         let checks;
         try {
-            checks = await (0, cancellation_js_1.awaitWithSignal)(reviewValues({ items: selected.map(cell => ({ item: cell.item, value: cell.value })) }, context), context.signal);
+            checks = await (0, cancellation_js_1.awaitWithSignal)(reviewValues({ items: selected.map((cell) => ({ item: cell.item, value: cell.value })) }, context), context.signal);
         }
         catch {
             context.signal.throwIfAborted();
@@ -110,7 +155,10 @@ function defineAnswerFlow(definition) {
             return;
         }
         context.signal.throwIfAborted();
-        if (!checks || typeof checks.get !== 'function' || typeof checks.keys !== 'function' || [...checks.keys()].some(id => !selected.some(cell => cell.item.id === id)))
+        if (!checks ||
+            typeof checks.get !== 'function' ||
+            typeof checks.keys !== 'function' ||
+            [...checks.keys()].some((id) => !selected.some((cell) => cell.item.id === id)))
             throw new TypeError('Invalid answer review ownership');
         const checked = new Map([...checks].map(([id, result]) => [id, (0, check_result_js_1.snapshotAnswerCheck)(result)]));
         for (const cell of selected) {
@@ -121,32 +169,140 @@ function defineAnswerFlow(definition) {
                 cell.knownReviewFailure = false;
         }
     }
-    const workflow = (0, workflow_js_1.defineWorkflow)({ id: 'answer-flow', entryNodeId: 'generate', nodes: [
-            { id: 'generate', description: 'Generate available items', startsRound: true, run: async (state, context) => { await generate(state.cells.filter(cell => cell.item.sourceStatus === 'ready'), false, context); }, routes: [{ id: 'to-validate', targetNodeId: 'validate' }] },
-            { id: 'validate', description: 'Check values and retain sanitized output', run: (state, context) => { check(state.cells.filter(cell => cell.item.sourceStatus === 'ready'), context); }, routes: [{ id: 'to-review', targetNodeId: 'review' }] },
-            { id: 'review', description: 'Review locally accepted values', run: async (state, context) => { await review(state.cells.filter(cell => cell.item.sourceStatus === 'ready'), context); observe('checked', state.cells, context); }, routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }] },
-            { id: 'select-repair', description: 'Select only failed available items', run: state => ({ pending: state.cells.filter(cell => cell.item.sourceStatus === 'ready' && issues(cell).length > 0) }), routes: [{ id: 'to-repair', conditionId: '{nid}.{rid}', when: (state, context) => state.pending.length > 0 && state.repairBudget.available && allowed(context), targetNodeId: 'repair' }, { id: 'to-deliver', targetNodeId: 'deliver' }] },
-            { id: 'repair', description: 'Use one bounded repair attempt', startsRound: true, run: async (state, context) => { if (!state.repairBudget.take())
-                    throw new TypeError('Answer repair budget exhausted'); await generate(state.pending, true, context); }, routes: [{ id: 'to-recheck', targetNodeId: 'recheck' }] },
-            { id: 'recheck', description: 'Recheck only repaired items', run: async (state, context) => { const generated = state.pending.filter(cell => cell.generated); check(generated, context); await review(generated, context); observe('repaired', state.pending, context); }, routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }] },
-            { id: 'deliver', description: 'Return accepted values or explicit fallback states', run: (state, context) => ({ result: state.cells.map(cell => {
+    const workflow = (0, workflow_js_1.defineWorkflow)({
+        id: 'answer-flow',
+        entryNodeId: 'generate',
+        nodes: [
+            {
+                id: 'generate',
+                description: 'Generate available items',
+                startsRound: true,
+                run: async (state, context) => {
+                    await generate(state.cells.filter((cell) => cell.item.sourceStatus === 'ready'), false, context);
+                },
+                routes: [{ id: 'to-validate', targetNodeId: 'validate' }],
+            },
+            {
+                id: 'validate',
+                description: 'Check values and retain sanitized output',
+                run: (state, context) => {
+                    check(state.cells.filter((cell) => cell.item.sourceStatus === 'ready'), context);
+                },
+                routes: [{ id: 'to-review', targetNodeId: 'review' }],
+            },
+            {
+                id: 'review',
+                description: 'Review locally accepted values',
+                run: async (state, context) => {
+                    await review(state.cells.filter((cell) => cell.item.sourceStatus === 'ready'), context);
+                    observe('checked', state.cells, context);
+                },
+                routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }],
+            },
+            {
+                id: 'select-repair',
+                description: 'Select only failed available items',
+                run: (state) => ({
+                    pending: state.cells.filter((cell) => cell.item.sourceStatus === 'ready' && issues(cell).length > 0),
+                }),
+                routes: [
+                    {
+                        id: 'to-repair',
+                        conditionId: '{nid}.{rid}',
+                        when: (state, context) => state.pending.length > 0 && state.repairBudget.available && allowed(context),
+                        targetNodeId: 'repair',
+                    },
+                    { id: 'to-deliver', targetNodeId: 'deliver' },
+                ],
+            },
+            {
+                id: 'repair',
+                description: 'Use one bounded repair attempt',
+                startsRound: true,
+                run: async (state, context) => {
+                    if (!state.repairBudget.take())
+                        throw new TypeError('Answer repair budget exhausted');
+                    await generate(state.pending, true, context);
+                },
+                routes: [{ id: 'to-recheck', targetNodeId: 'recheck' }],
+            },
+            {
+                id: 'recheck',
+                description: 'Recheck only repaired items',
+                run: async (state, context) => {
+                    const generated = state.pending.filter((cell) => cell.generated);
+                    check(generated, context);
+                    await review(generated, context);
+                    observe('repaired', state.pending, context);
+                },
+                routes: [{ id: 'to-select-repair', targetNodeId: 'select-repair' }],
+            },
+            {
+                id: 'deliver',
+                description: 'Return accepted values or explicit fallback states',
+                run: (state, context) => ({
+                    result: state.cells.map((cell) => {
                         context.signal.throwIfAborted();
                         const errors = issues(cell);
                         if (cell.item.sourceStatus === 'ready' && !errors.length && cell.hasValue)
-                            return { item: cell.item, value: cell.value, status: 'accepted', issues: errors, checks: { local: cell.local, review: cell.review } };
+                            return {
+                                item: cell.item,
+                                value: cell.value,
+                                status: 'accepted',
+                                issues: errors,
+                                checks: { local: cell.local, review: cell.review },
+                            };
                         const outcome = (0, synchronous_js_1.synchronous)(fallbackValue({ item: cell.item, issues: errors }, context), 'Answer fallback must be synchronous');
-                        if (!outcome || typeof outcome.handled !== 'boolean' || (outcome.handled && !('value' in outcome)))
+                        if (!outcome ||
+                            typeof outcome.handled !== 'boolean' ||
+                            (outcome.handled && !('value' in outcome)))
                             throw new TypeError('Invalid answer fallback outcome');
-                        return { item: cell.item, value: outcome.handled ? outcome.value : undefined, status: outcome.handled ? 'fallback' : 'blocked', issues: errors, checks: { local: cell.local, review: cell.review } };
-                    }) }), routes: [{ id: 'complete', complete: state => state.result }] },
-        ] });
-    return Object.freeze({ async run(request, context) {
+                        return {
+                            item: cell.item,
+                            value: outcome.handled ? outcome.value : undefined,
+                            status: outcome.handled ? 'fallback' : 'blocked',
+                            issues: errors,
+                            checks: { local: cell.local, review: cell.review },
+                        };
+                    }),
+                }),
+                routes: [{ id: 'complete', complete: (state) => state.result }],
+            },
+        ],
+    });
+    return Object.freeze({
+        /**
+         * Run one answer batch.
+         *
+         * @param request - Input ids the batch must cover and the items to answer; validated before
+         *   any handler runs.
+         * @param context - Operation context supplying app, signal and diagnostics.
+         * @returns One accepted, fallback or blocked result per item, in request order.
+         * @throws TypeError For an invalid batch or handler output, or when the repair budget is
+         *   exhausted without a final result.
+         */
+        async run(request, context) {
             context.signal.throwIfAborted();
             (0, batch_js_1.validateAnswerBatch)(request.inputIds, request.items, maxItems);
-            const cells = request.items.map(item => ({ item: Object.freeze({ id: item.id, data: item.data, sourceStatus: item.sourceStatus, inputIds: Object.freeze([...item.inputIds]) }),
-                hasValue: false, local: { status: 'not-run', issues: [] }, review: { status: 'not-run', issues: [] }, knownReviewFailure: false }));
-            return new engine_js_1.AgentCoreEngine({ maxRounds: maxRepairs + 1,
-                errors: { exhausted: () => new TypeError('Answer flow exhausted') }, execution: { signal: context.signal, diagnostics: context.diagnostics },
-            }).bindWorkflow(workflow, context.app).run({ cells, pending: [], repairBudget: new workflow_js_1.AttemptBudget(maxRepairs) });
-        } });
+            const cells = request.items.map((item) => ({
+                item: Object.freeze({
+                    id: item.id,
+                    data: item.data,
+                    sourceStatus: item.sourceStatus,
+                    inputIds: Object.freeze([...item.inputIds]),
+                }),
+                hasValue: false,
+                local: { status: 'not-run', issues: [] },
+                review: { status: 'not-run', issues: [] },
+                knownReviewFailure: false,
+            }));
+            return new engine_js_1.AgentCoreEngine({
+                maxRounds: maxRepairs + 1,
+                errors: { exhausted: () => new TypeError('Answer flow exhausted') },
+                execution: { signal: context.signal, diagnostics: context.diagnostics },
+            })
+                .bindWorkflow(workflow, context.app)
+                .run({ cells, pending: [], repairBudget: new workflow_js_1.AttemptBudget(maxRepairs) });
+        },
+    });
 }

package/dist/cjs/kits/answering/index.js

@@ -15,6 +15,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Answering = void 0;
+/**
+ * Answering Kit entry: batch validation, per-value checks, task/reader catalogs and the
+ * generate-check-review-repair workflow.
+ *
+ * Place in the package: an optional App-side library for answering a bounded batch of items.
+ * Models, readers, checks, fallbacks and repair policy are supplied by the App; this module
+ * owns their composition, bounds and status aggregation. Core never imports it.
+ *
+ * Exports: everything from `./flow.js`, `./tasks.js`, `./batch.js` and `./checks.js`, plus the
+ * `Answering` namespace object.
+ */
 __exportStar(require("./flow.js"), exports);
 __exportStar(require("./tasks.js"), exports);
 __exportStar(require("./batch.js"), exports);
@@ -23,4 +34,11 @@ const tasks_js_1 = require("./tasks.js");
 const checks_js_1 = require("./checks.js");
 const flow_js_1 = require("./flow.js");
 const batch_js_1 = require("./batch.js");
-exports.Answering = Object.freeze({ defineAnswerTaskCatalog: tasks_js_1.defineAnswerTaskCatalog, defineAnswerReaderCatalog: tasks_js_1.defineAnswerReaderCatalog, defineAnswerCheckCatalog: checks_js_1.defineAnswerCheckCatalog, defineAnswerFlow: flow_js_1.defineAnswerFlow, validateAnswerBatch: batch_js_1.validateAnswerBatch });
+/** Namespace object for callers that prefer one import over named helpers. */
+exports.Answering = Object.freeze({
+    defineAnswerTaskCatalog: tasks_js_1.defineAnswerTaskCatalog,
+    defineAnswerReaderCatalog: tasks_js_1.defineAnswerReaderCatalog,
+    defineAnswerCheckCatalog: checks_js_1.defineAnswerCheckCatalog,
+    defineAnswerFlow: flow_js_1.defineAnswerFlow,
+    validateAnswerBatch: batch_js_1.validateAnswerBatch,
+});

package/dist/cjs/kits/answering/tasks.js

@@ -2,36 +2,84 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineAnswerReaderCatalog = defineAnswerReaderCatalog;
 exports.defineAnswerTaskCatalog = defineAnswerTaskCatalog;
+/**
+ * Answering Kit: answer tasks, their readers, schemas and metadata.
+ *
+ * Place in the package: part of the `answering` Kit. A task binds an intent set, a scope, an
+ * output contract, check ids and a reader; this module compiles that binding, validates the
+ * reader ids and exposes read/describe entry points. Readers stay App-owned I/O.
+ *
+ * Exports: `defineAnswerReaderCatalog`, `defineAnswerTaskCatalog`, and the task/reader types.
+ */
 const catalog_js_1 = require("../../utils/catalog.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
 const object_js_1 = require("../../utils/object.js");
 const cancellation_js_1 = require("../../utils/cancellation.js");
 const schema_adapter_js_1 = require("../../utils/schema-adapter.js");
-/** Task ids, schema, readers, outputs and checks have one compiled authority. */
+/**
+ * Compile a reader catalog.
+ *
+ * @param definitions - Readers with unique ids and a `read` handler.
+ * @returns A frozen catalog; unknown ids fail through `require`.
+ * @throws TypeError When a reader has no `read` handler.
+ */
 function defineAnswerReaderCatalog(definitions) {
-    return (0, catalog_js_1.readonlyCatalog)(definitions.map(reader => {
+    return (0, catalog_js_1.readonlyCatalog)(definitions.map((reader) => {
         if (typeof reader.read !== 'function')
             throw new TypeError('Invalid answer reader');
         return Object.freeze({ id: reader.id, read: reader.read.bind(reader) });
-    }), id => new TypeError(`Unknown answer reader: ${id}`));
+    }), (id) => new TypeError(`Unknown answer reader: ${id}`));
 }
+/**
+ * Compile the answer task catalog from its declarations and shared ports.
+ *
+ * Task ids, schemas, readers, outputs and checks have one compiled authority: a task can only
+ * reference a reader or check that the ports actually registered, and metadata is cloned and
+ * frozen so later mutation by the caller cannot change a registered task.
+ *
+ * @param definitions - Task declarations with identity, reader/output/scope references,
+ *   intent ids, check ids, input schema and metadata.
+ * @param ports - Registered readers, checks, outputs and an optional definition assertion.
+ * @returns A frozen catalog extended with `describe`, `read` and `readAsync`.
+ * @throws TypeError For a task with missing identity, an unknown reader/output/check, empty or
+ *   duplicate intent ids, a duplicate check id, or a failed definition assertion.
+ */
 function defineAnswerTaskCatalog(definitions, ports) {
     const readers = defineAnswerReaderCatalog([...ports.readers.values()]);
     const checkIds = ports.checks.ids();
     const assertDefinition = ports.assertDefinition?.bind(ports);
     const outputs = new Set(ports.outputs.ids());
-    const tasks = definitions.map(definition => {
-        if (!definition.id?.trim() || !definition.description?.trim() || !readers.has(definition.readerId) || !outputs.has(definition.outputId)
-            || !Array.isArray(definition.intentIds) || !definition.intentIds.length || definition.intentIds.some(id => typeof id !== 'string' || !id.trim()) || new Set(definition.intentIds).size !== definition.intentIds.length
-            || !Array.isArray(definition.checkIds) || new Set(definition.checkIds).size !== definition.checkIds.length || definition.checkIds.some(id => !checkIds.includes(id)))
+    const tasks = definitions.map((definition) => {
+        if (!definition.id?.trim() ||
+            !definition.description?.trim() ||
+            !readers.has(definition.readerId) ||
+            !outputs.has(definition.outputId) ||
+            !Array.isArray(definition.intentIds) ||
+            !definition.intentIds.length ||
+            definition.intentIds.some((id) => typeof id !== 'string' || !id.trim()) ||
+            new Set(definition.intentIds).size !== definition.intentIds.length ||
+            !Array.isArray(definition.checkIds) ||
+            new Set(definition.checkIds).size !== definition.checkIds.length ||
+            definition.checkIds.some((id) => !checkIds.includes(id)))
             throw new TypeError(`Invalid answer task: ${definition.id}`);
         const metadata = structuredClone(definition.metadata);
         (0, object_js_1.freezeSchema)(metadata);
-        const task = Object.freeze({ ...definition, id: definition.id, description: definition.description, readerId: definition.readerId, outputId: definition.outputId, scopeId: definition.scopeId, intentIds: Object.freeze([...definition.intentIds]), checkIds: Object.freeze([...definition.checkIds]), inputSchema: (0, schema_adapter_js_1.snapshotSchemaAdapter)(definition.inputSchema), metadata });
+        const task = Object.freeze({
+            ...definition,
+            id: definition.id,
+            description: definition.description,
+            readerId: definition.readerId,
+            outputId: definition.outputId,
+            scopeId: definition.scopeId,
+            intentIds: Object.freeze([...definition.intentIds]),
+            checkIds: Object.freeze([...definition.checkIds]),
+            inputSchema: (0, schema_adapter_js_1.snapshotSchemaAdapter)(definition.inputSchema),
+            metadata,
+        });
         (0, synchronous_js_1.assertion)(assertDefinition?.(task), 'Task assertions must return void synchronously');
         return task;
     });
-    const catalog = (0, catalog_js_1.readonlyCatalog)(tasks, id => new TypeError(`Unknown answer task: ${id}`));
+    const catalog = (0, catalog_js_1.readonlyCatalog)(tasks, (id) => new TypeError(`Unknown answer task: ${id}`));
     const prepare = (request, context) => {
         context.signal.throwIfAborted();
         const task = catalog.require(request.taskId);
@@ -39,17 +87,44 @@ function defineAnswerTaskCatalog(definitions, ports) {
         context.signal.throwIfAborted();
         return { input, task, reader: readers.require(task.readerId) };
     };
-    return Object.freeze({ ...catalog,
-        describe: () => tasks.map(({ inputSchema, ...task }) => ({ ...task, inputJsonSchema: inputSchema.jsonSchema })),
+    return Object.freeze({
+        ...catalog,
+        /** Task metadata with the JSON schema flattened for model or admin presentation. */
+        describe: () => tasks.map(({ inputSchema, ...task }) => ({
+            ...task,
+            inputJsonSchema: inputSchema.jsonSchema,
+        })),
+        /**
+         * Read evidence through a task's registered reader, synchronously.
+         *
+         * @throws TypeError For an unknown task, a parse failure, or a reader returning a Promise.
+         */
         read(request, context) {
             const { input, task, reader } = prepare(request, context);
-            const value = (0, synchronous_js_1.synchronous)(reader.read(input, { ...context, app: context.app, signal: context.signal, diagnostics: context.diagnostics, task }), 'Synchronous answer readers must not return a Promise');
+            const value = (0, synchronous_js_1.synchronous)(reader.read(input, {
+                ...context,
+                app: context.app,
+                signal: context.signal,
+                diagnostics: context.diagnostics,
+                task,
+            }), 'Synchronous answer readers must not return a Promise');
             context.signal.throwIfAborted();
             return value;
         },
+        /**
+         * Read evidence through a task's registered reader, awaiting an async reader.
+         *
+         * @throws TypeError For an unknown task or a parse failure; aborts with the caller's signal.
+         */
         async readAsync(request, context) {
             const { input, task, reader } = prepare(request, context);
-            const value = await (0, cancellation_js_1.awaitWithSignal)(reader.read(input, { ...context, app: context.app, signal: context.signal, diagnostics: context.diagnostics, task }), context.signal);
+            const value = await (0, cancellation_js_1.awaitWithSignal)(reader.read(input, {
+                ...context,
+                app: context.app,
+                signal: context.signal,
+                diagnostics: context.diagnostics,
+                task,
+            }), context.signal);
             context.signal.throwIfAborted();
             return value;
         },

package/dist/cjs/kits/artifacts.js

@@ -2,19 +2,41 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Artifacts = void 0;
 exports.defineArtifactCatalog = defineArtifactCatalog;
+/**
+ * Artifacts Kit: resolve opaque artifact references through App-registered resolvers.
+ *
+ * Place in the package: an optional App-side library. A reference only names a resolver and
+ * an artifact; the resolver, not this module, establishes access, provenance and whether the
+ * referenced revision is still current. Nothing is cached or persisted here.
+ *
+ * Exports: `defineArtifactCatalog`, `Artifacts`, and the artifact reference/resolver types.
+ */
 const cancellation_js_1 = require("../utils/cancellation.js");
 const catalog_js_1 = require("../utils/catalog.js");
 function snapshotArtifactReference(reference) {
     if (!reference || typeof reference !== 'object')
         throw new TypeError('Invalid artifact reference');
     const { resolverId, artifactId, revision } = reference;
-    if (typeof resolverId !== 'string' || !resolverId.trim() || typeof artifactId !== 'string' || !artifactId.trim()
-        || (revision !== undefined && (typeof revision !== 'string' || !revision.trim())))
+    if (typeof resolverId !== 'string' ||
+        !resolverId.trim() ||
+        typeof artifactId !== 'string' ||
+        !artifactId.trim() ||
+        (revision !== undefined && (typeof revision !== 'string' || !revision.trim())))
         throw new TypeError('Invalid artifact reference');
     return Object.freeze({ resolverId, artifactId, ...(revision === undefined ? {} : { revision }) });
 }
+/**
+ * Compile a catalog of artifact resolvers plus a checked `resolve` entry point.
+ *
+ * @param definitions - Resolvers keyed by their own non-empty `id`; duplicate ids are rejected
+ *   by the underlying catalog.
+ * @returns A frozen catalog (`ids`/`has`/`get`/`require`/`values`/`entries`) extended with
+ *   `resolve(reference, context)`.
+ * @throws TypeError At construction for malformed resolver definitions, and from `resolve`
+ *   for an unknown resolver, an invalid reference snapshot, or a missing `OperationContext`.
+ */
 function defineArtifactCatalog(definitions) {
-    const compiled = definitions.map(definition => {
+    const compiled = definitions.map((definition) => {
         if (!definition || typeof definition !== 'object')
             throw new TypeError('Use an artifact resolver id and OperationContext');
         const { id, resolve } = definition;
@@ -22,7 +44,16 @@ function defineArtifactCatalog(definitions) {
             throw new TypeError('Invalid artifact resolver');
         return Object.freeze({ id, resolve: resolve.bind(definition) });
     });
-    const catalog = (0, catalog_js_1.readonlyCatalog)(compiled, id => new TypeError(`Unregistered artifact resolver: ${id}`));
+    const catalog = (0, catalog_js_1.readonlyCatalog)(compiled, (id) => new TypeError(`Unregistered artifact resolver: ${id}`));
+    /**
+     * Resolve one reference through its registered resolver.
+     *
+     * @param reference - Resolver id, artifact id and optional revision; snapshotted and frozen
+     *   before the call so a handler cannot observe later mutation.
+     * @param context - Operation context supplying the abort signal.
+     * @returns The resolver's value.
+     * @throws TypeError For a malformed reference or context, or an unknown resolver id.
+     */
     async function resolve(reference, context) {
         if (!context?.signal)
             throw new TypeError('Artifact resolution requires OperationContext');
@@ -35,4 +66,5 @@ function defineArtifactCatalog(definitions) {
     }
     return Object.freeze({ ...catalog, resolve });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Artifacts = Object.freeze({ defineArtifactCatalog });

package/dist/cjs/kits/candidates.js

@@ -3,7 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Candidates = void 0;
 exports.defineCandidateSelection = defineCandidateSelection;
 const rules_js_1 = require("../utils/rules.js");
-/** Alternative proposals are bounded and shallow; accepting a task closes this capability. */
+/**
+ * Compile an alternative-proposal envelope contract.
+ *
+ * Alternative proposals are bounded and shallow; accepting a task closes this capability.
+ * A value that is not an object, or that does not carry the candidate field, is treated as a
+ * single implicit candidate and returned as-is. Once the envelope is present it must contain
+ * only that field, and its array must hold between `minCandidates` (default 1) and
+ * `maxCandidates` distinct candidate objects that do not themselves repeat the field.
+ *
+ * @param definition - Field name, bounds, optional error wording and diagnostic tags.
+ * @returns A frozen selector exposing `field`, the resolved bounds and `parse`.
+ * @throws TypeError When the field name or bounds are invalid.
+ */
 function defineCandidateSelection(definition) {
     const { field, error: configuredError, maxCandidates: max } = definition;
     const error = typeof configuredError === 'function' ? configuredError.bind(definition) : configuredError;
@@ -11,8 +23,22 @@ function defineCandidateSelection(definition) {
     const tags = [...(definition.tags ?? [])];
     (0, rules_js_1.breakWhile)([
         { occur: () => !field.trim(), error: 'Missing candidate field' },
-        { occur: [() => !Number.isSafeInteger(min) || !Number.isSafeInteger(max), () => min < 1 || max < min], error: 'Invalid candidate bounds' },
+        {
+            occur: [
+                () => !Number.isSafeInteger(min) || !Number.isSafeInteger(max),
+                () => min < 1 || max < min,
+            ],
+            error: 'Invalid candidate bounds',
+        },
     ]);
+    /**
+     * Unpack the candidates from one parsed reply value.
+     *
+     * @param request - The raw value plus whether proposals are still allowed at this point.
+     * @returns The candidate list, or `[value]` when no envelope is present.
+     * @throws TypeError When `allowed` is not boolean, or when the envelope is disallowed,
+     *   malformed, out of bounds or contains nested candidate envelopes.
+     */
     function parse({ value, allowed }) {
         if (typeof allowed !== 'boolean')
             throw new TypeError('Candidate availability must be boolean');
@@ -21,9 +47,24 @@ function defineCandidateSelection(definition) {
         const candidates = value[field];
         (0, rules_js_1.breakWhile)([
             { occur: () => !allowed, error, tags: ['availability'] },
-            { occur: () => Array.isArray(value) || Object.keys(value).length !== 1, error, tags: ['envelope'] },
-            { occur: [() => !Array.isArray(candidates), () => candidates.length < min || candidates.length > max], error, tags: ['selection'] },
-            { occur: () => candidates.some(candidate => invalidCandidate(candidate, field)), error, tags: ['members'] },
+            {
+                occur: () => Array.isArray(value) || Object.keys(value).length !== 1,
+                error,
+                tags: ['envelope'],
+            },
+            {
+                occur: [
+                    () => !Array.isArray(candidates),
+                    () => candidates.length < min || candidates.length > max,
+                ],
+                error,
+                tags: ['selection'],
+            },
+            {
+                occur: () => candidates.some((candidate) => invalidCandidate(candidate, field)),
+                error,
+                tags: ['members'],
+            },
         ], tags);
         return candidates;
     }
@@ -34,4 +75,5 @@ function invalidCandidate(value, field) {
         return true;
     return Object.hasOwn(value, field);
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Candidates = Object.freeze({ defineCandidateSelection });