@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/kits/family.js

@@ -2,39 +2,92 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.familyOperations = exports.Family = void 0;
 exports.defineAgentFamily = defineAgentFamily;
+/**
+ * Family Kit: version App state that hangs off Core branches, with fork, merge and promote.
+ *
+ * Place in the package: an optional App-side library. A family is a bounded, expiring record
+ * of immutable versions; each version pairs a branch snapshot with App state. The Kit owns
+ * revision checks, capacity, retention and lineage rules; the store, authorization, validation
+ * and merge policy stay with the App. No executable function or authority is restored here.
+ *
+ * Exports: `defineAgentFamily`, `Family`, the family record/version/operation types and
+ * `familyOperations`.
+ */
 const invocation_js_1 = require("../utils/invocation.js");
 const cancellation_js_1 = require("../utils/cancellation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
 const branch_js_1 = require("../execution/branch.js");
-/** Versioned App data around existing Engine branches. No executable functions or authority are restored. */
+/**
+ * Compile a versioned family backed by an App-owned compare-and-swap store.
+ *
+ * Every mutation reads the record, verifies the caller's expected revision, then commits with
+ * a compare-and-swap, so concurrent writers fail with a revision conflict rather than
+ * overwriting each other. Reads are also treated as policy checks because the App binds its
+ * read rules into the store it supplies.
+ *
+ * @param definition - Store, authorization, validation, state predicate, branch/state snapshots
+ *   and optional merge handler, clock and bounds.
+ * @returns A frozen family with `read`, `create`, `fork`, `merge` and `promote`.
+ * @throws A configured error (often `TypeError`) for an invalid id, expired or unknown record,
+ *   revision conflict, exhausted capacity, lineage mismatch, missing merge configuration,
+ *   invalid merge result, or changed active version.
+ */
 function defineAgentFamily(definition) {
-    const store = { load: definition.store.load.bind(definition.store), compareAndSwap: definition.store.compareAndSwap.bind(definition.store) };
+    const store = {
+        load: definition.store.load.bind(definition.store),
+        compareAndSwap: definition.store.compareAndSwap.bind(definition.store),
+    };
     const authorize = definition.authorize.bind(definition), validate = definition.validate.bind(definition);
     const isState = definition.isState.bind(definition), merge = definition.merge?.bind(definition), now = definition.now?.bind(definition) ?? Date.now;
+    // Bounds are encoded in the record itself: 32 versions and seven days of retention keep the
+    // snapshot small enough to clone and compare on every operation.
     const maxVersions = definition.maxVersions ?? 32, retentionMs = definition.retentionMs ?? 7 * 86400_000;
-    (0, rules_js_1.breakWhile)(!Number.isSafeInteger(maxVersions) || maxVersions < 1 || !Number.isSafeInteger(retentionMs) || retentionMs < 1, 'Invalid family bounds');
+    (0, rules_js_1.breakWhile)(!Number.isSafeInteger(maxVersions) ||
+        maxVersions < 1 ||
+        !Number.isSafeInteger(retentionMs) ||
+        retentionMs < 1, 'Invalid family bounds');
     const validId = (id) => typeof id === 'string' && !!id.trim() && id.length <= 200;
     const stateSnapshot = (value) => {
         (0, rules_js_1.breakWhile)(!(0, synchronous_js_1.booleanResult)(isState(value), 'Family state predicates must be synchronous'), 'Invalid family state');
         return structuredClone(value);
     };
+    /**
+     * Load, validate and clone a family record.
+     *
+     * @param id - Family id, at most 200 characters.
+     * @param context - Operation context supplying the abort signal.
+     * @returns A cloned record whose versions, branches and states all passed validation.
+     * @throws A configured error for an invalid id, a missing/expired record, or an inconsistent
+     *   version.
+     */
     const read = async (id, context) => {
         context.signal.throwIfAborted();
         (0, rules_js_1.breakWhile)(!validId(id), 'Invalid family id');
         const record = structuredClone(await (0, cancellation_js_1.awaitWithSignal)(store.load(id), context.signal));
         context.signal.throwIfAborted();
-        (0, rules_js_1.breakWhile)(!record || record.id !== id || !Number.isFinite(record.expiresAtMs) || record.expiresAtMs <= now() || !Number.isSafeInteger(record.revision) || record.revision < 1
-            || !Array.isArray(record.versions) || !record.versions.length || record.versions.length > maxVersions || !record.versions.some(version => version.id === record.activeId), 'Family unavailable');
-        const ids = new Set(record.versions.map(version => version.id));
+        (0, rules_js_1.breakWhile)(!record ||
+            record.id !== id ||
+            !Number.isFinite(record.expiresAtMs) ||
+            record.expiresAtMs <= now() ||
+            !Number.isSafeInteger(record.revision) ||
+            record.revision < 1 ||
+            !Array.isArray(record.versions) ||
+            !record.versions.length ||
+            record.versions.length > maxVersions ||
+            !record.versions.some((version) => version.id === record.activeId), 'Family unavailable');
+        const ids = new Set(record.versions.map((version) => version.id));
         (0, rules_js_1.breakWhile)(ids.size !== record.versions.length, 'Duplicate family version');
         for (const item of record.versions) {
-            (0, rules_js_1.breakWhile)(!validId(item.id) || !Number.isFinite(item.createdAtMs) || item.createdAtMs < 0
-                || [item.parentId, item.baseId, item.mergeSourceId].some(value => value !== undefined && !ids.has(value)), 'Invalid family version');
+            (0, rules_js_1.breakWhile)(!validId(item.id) ||
+                !Number.isFinite(item.createdAtMs) ||
+                item.createdAtMs < 0 ||
+                [item.parentId, item.baseId, item.mergeSourceId].some((value) => value !== undefined && !ids.has(value)), 'Invalid family version');
             (0, branch_js_1.snapshotBranch)(item.branch);
             stateSnapshot(item.state);
         }
-        // Reading policy is part of the App's bound store. Mutations also require their explicit operation grant.
+        // Reading policy is part of the App's bound store. Mutations also require their explicit
+        // operation grant.
         context.signal.throwIfAborted();
         return structuredClone(record);
     };
@@ -54,7 +107,7 @@ function defineAgentFamily(definition) {
         return record;
     };
     const version = (record, id) => {
-        const selected = record.versions.find(item => item.id === id);
+        const selected = record.versions.find((item) => item.id === id);
         (0, rules_js_1.breakWhile)(!selected, 'Unknown family version');
         return selected;
     };
@@ -64,50 +117,127 @@ function defineAgentFamily(definition) {
         return commit({ ...record, revision: record.revision + 1, versions: [...record.versions, candidate] }, record.revision, context);
     };
     return Object.freeze({
+        /** Clone and validate one family record through the same read path used by mutations. */
         read,
+        /**
+         * Create a family with one initial version.
+         *
+         * @param request - Family id plus its first branch and state.
+         * @param context - Operation context; authorization receives `'create'` and no record.
+         * @returns The committed record at revision 1.
+         * @throws A configured error for an invalid or existing id, or failed authorization or
+         *   validation.
+         */
         async create(request, context) {
             context.signal.throwIfAborted();
             const { id } = request;
             (0, rules_js_1.breakWhile)(!validId(id), 'Invalid family id');
             const branch = (0, branch_js_1.snapshotBranch)(request.branch), state = structuredClone(request.state);
-            (0, rules_js_1.breakWhile)(!!await (0, cancellation_js_1.awaitWithSignal)(store.load(id), context.signal), 'Family already exists');
+            (0, rules_js_1.breakWhile)(!!(await (0, cancellation_js_1.awaitWithSignal)(store.load(id), context.signal)), 'Family already exists');
             await (0, cancellation_js_1.awaitAssertion)(() => authorize('create', undefined, context), context.signal, 'Family authorization must return void');
-            const candidate = { id: (0, invocation_js_1.invocationId)(), branch, state: stateSnapshot(state), createdAtMs: now() };
+            const candidate = {
+                id: (0, invocation_js_1.invocationId)(),
+                branch,
+                state: stateSnapshot(state),
+                createdAtMs: now(),
+            };
             await (0, cancellation_js_1.awaitAssertion)(() => validate(structuredClone(candidate), context), context.signal, 'Family validation must return void');
-            return commit({ id, revision: 1, activeId: candidate.id, expiresAtMs: now() + retentionMs, versions: [candidate] }, undefined, context);
+            return commit({
+                id,
+                revision: 1,
+                activeId: candidate.id,
+                expiresAtMs: now() + retentionMs,
+                versions: [candidate],
+            }, undefined, context);
         },
+        /**
+         * Add a child version derived from one existing version.
+         *
+         * @param request - Family id, expected revision, parent version id, new branch and state.
+         * @param context - Operation context; authorization receives `'fork'` and the record.
+         * @returns The committed record with the new version appended.
+         * @throws A configured error for a stale revision, unknown parent, broken lineage or full
+         *   capacity.
+         */
         async fork(request, context) {
             context.signal.throwIfAborted();
             const { id, revision, parentId } = request, state = structuredClone(request.state);
             const branch = (0, branch_js_1.snapshotBranch)(request.branch);
             const record = await check('fork', id, revision, context), parent = version(record, parentId);
-            (0, rules_js_1.breakWhile)(branch.agentId !== parent.branch.agentId || branch.parentBranchId !== parent.branch.branchId
-                || branch.parentAgentVersionId !== parent.branch.agentVersionId || branch.branchId === parent.branch.branchId, 'Fork lineage mismatch');
-            return add(record, { id: (0, invocation_js_1.invocationId)(), parentId: parent.id, baseId: parent.id, branch, state: stateSnapshot(state), createdAtMs: now() }, context);
+            (0, rules_js_1.breakWhile)(branch.agentId !== parent.branch.agentId ||
+                branch.parentBranchId !== parent.branch.branchId ||
+                branch.parentAgentVersionId !== parent.branch.agentVersionId ||
+                branch.branchId === parent.branch.branchId, 'Fork lineage mismatch');
+            return add(record, {
+                id: (0, invocation_js_1.invocationId)(),
+                parentId: parent.id,
+                baseId: parent.id,
+                branch,
+                state: stateSnapshot(state),
+                createdAtMs: now(),
+            }, context);
         },
+        /**
+         * Merge a source version into a target version over their shared base.
+         *
+         * Conflicts are reported, never resolved here: a non-empty conflict list returns
+         * `saved: false` with the unchanged record, so the App decides how to reconcile.
+         *
+         * @param request - Family id, expected revision and the base, target and source version ids.
+         * @param context - Operation context; authorization receives `'merge'` and the record.
+         * @returns `{ saved, record, conflicts }`.
+         * @throws A configured error for a stale revision, missing versions, no merge handler, a
+         *   missing shared base, or an invalid merge result.
+         */
         async merge(request, context) {
             const { id, revision, baseId, targetId, sourceId } = request;
             const record = await check('merge', id, revision, context);
             (0, rules_js_1.breakWhile)(!merge, 'Family merge is not configured');
             const base = version(record, baseId), target = version(record, targetId), source = version(record, sourceId);
-            (0, rules_js_1.breakWhile)(source.baseId !== base.id || target.id !== base.id && target.baseId !== base.id, 'Merge requires a shared base');
-            const result = await (0, cancellation_js_1.awaitWithSignal)(merge({ base: stateSnapshot(base.state), target: stateSnapshot(target.state), source: stateSnapshot(source.state) }, context), context.signal);
-            (0, rules_js_1.breakWhile)(!result || !Array.isArray(result.conflicts) || result.conflicts.some(value => typeof value !== 'string'), 'Invalid merge result');
+            (0, rules_js_1.breakWhile)(source.baseId !== base.id || (target.id !== base.id && target.baseId !== base.id), 'Merge requires a shared base');
+            const result = await (0, cancellation_js_1.awaitWithSignal)(merge({
+                base: stateSnapshot(base.state),
+                target: stateSnapshot(target.state),
+                source: stateSnapshot(source.state),
+            }, context), context.signal);
+            (0, rules_js_1.breakWhile)(!result ||
+                !Array.isArray(result.conflicts) ||
+                result.conflicts.some((value) => typeof value !== 'string'), 'Invalid merge result');
             if (result.conflicts.length)
                 return { saved: false, record, conflicts: [...result.conflicts] };
-            const candidate = { id: (0, invocation_js_1.invocationId)(), parentId: target.id, baseId: target.id, mergeSourceId: source.id,
-                branch: (0, branch_js_1.snapshotBranch)(source.branch), state: stateSnapshot(result.value), createdAtMs: now() };
+            const candidate = {
+                id: (0, invocation_js_1.invocationId)(),
+                parentId: target.id,
+                baseId: target.id,
+                mergeSourceId: source.id,
+                branch: (0, branch_js_1.snapshotBranch)(source.branch),
+                state: stateSnapshot(result.value),
+                createdAtMs: now(),
+            };
             return { saved: true, record: await add(record, candidate, context), conflicts: [] };
         },
+        /**
+         * Make an existing version the active one.
+         *
+         * @param request - Family id, expected revision, candidate id and the active id the caller
+         *   believes is current.
+         * @param context - Operation context; authorization receives `'promote'` and the record.
+         * @returns The committed record pointing at the candidate.
+         * @throws A configured error for a stale revision or active id, an unrelated candidate, or
+         *   failed validation.
+         */
         async promote(request, context) {
             const { id, revision, candidateId, expectedActiveId } = request;
             const record = await check('promote', id, revision, context), candidate = version(record, candidateId);
-            (0, rules_js_1.breakWhile)(record.activeId !== expectedActiveId || candidate.id !== record.activeId && candidate.baseId !== record.activeId, 'Active family version changed');
+            (0, rules_js_1.breakWhile)(record.activeId !== expectedActiveId ||
+                (candidate.id !== record.activeId && candidate.baseId !== record.activeId), 'Active family version changed');
             await (0, cancellation_js_1.awaitAssertion)(() => validate(structuredClone(candidate), context), context.signal, 'Family validation must return void');
             return commit({ ...record, revision: record.revision + 1, activeId: candidate.id }, record.revision, context);
         },
     });
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Family = Object.freeze({ defineAgentFamily });
+/** Operation names accepted by the family `authorize` hook. */
 var family_js_1 = require("../structs/kits/family.js");
 Object.defineProperty(exports, "familyOperations", { enumerable: true, get: function () { return family_js_1.familyOperations; } });

package/dist/cjs/kits/index.js

@@ -15,7 +15,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reciprocalRankFusion = exports.VectorSearch = exports.ModelCalls = exports.TextSearch = exports.TextSkills = exports.Candidates = exports.Policies = exports.Evidence = exports.Retrieval = exports.Aggregation = exports.Projection = exports.Delivery = exports.Normalization = exports.Presentation = exports.Answering = exports.Knowledge = exports.Tools = exports.Intents = exports.Interaction = void 0;
-/** Explicit bulk Kit entry; applications normally import the individual Kit path. */
+/**
+ * Explicit bulk Kit entry.
+ *
+ * Kits are optional, App-side business libraries. An application may consume a single Kit
+ * path; this file only exists for callers that prefer one import for the whole set. Core
+ * never imports from this directory, so nothing here becomes a runtime requirement.
+ *
+ * Exports: the Kit namespaces (`Interaction`, `Intents`, `Tools`, `Knowledge`, `Answering`,
+ * `Presentation`, `Normalization`, `Delivery`, `Projection`, `Aggregation`, `Retrieval`,
+ * `Evidence`, `Policies`, `Candidates`, `TextSkills`, `TextSearch`, `ModelCalls`,
+ * `VectorSearch`) plus every Kit type. Individual Kit paths stay the default.
+ */
 var index_js_1 = require("./interaction/index.js");
 Object.defineProperty(exports, "Interaction", { enumerable: true, get: function () { return index_js_1.Interaction; } });
 var index_js_2 = require("./intents/index.js");

package/dist/cjs/kits/inference.js

@@ -8,35 +8,97 @@ const cancellation_js_1 = require("../utils/cancellation.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const errors_js_2 = require("../errors.js");
 const protocol_registry_js_1 = require("../utils/protocol-registry.js");
+/**
+ * Frozen catalog of model bindings plus a checked invocation entry point.
+ *
+ * Registration happens once in the constructor; the catalog is never mutated afterwards, so a
+ * caller cannot swap a provider in the middle of a run.
+ */
 class ModelCalls {
     sequence = 0;
     bindings = new protocol_registry_js_1.ProtocolRegistry();
+    /**
+     * @param bindings - Bindings to register; each needs a non-blank `identity` and an `invoke`.
+     * @throws TypeError When a binding is malformed or two bindings share an id.
+     */
     constructor(bindings) {
         for (const binding of bindings) {
             if (!binding.identity?.trim() || typeof binding.invoke !== 'function')
                 throw new TypeError('Invalid model binding');
-            this.bindings.set(binding.id, Object.freeze({ id: binding.id, identity: binding.identity, invoke: binding.invoke.bind(binding),
-                assertInput: binding.assertInput?.bind(binding), assertOutput: binding.assertOutput?.bind(binding) }));
+            this.bindings.set(binding.id, Object.freeze({
+                id: binding.id,
+                identity: binding.identity,
+                invoke: binding.invoke.bind(binding),
+                assertInput: binding.assertInput?.bind(binding),
+                assertOutput: binding.assertOutput?.bind(binding),
+            }));
         }
     }
-    get definitions() { return Object.freeze([...this.bindings.values()]); }
-    ids() { return this.bindings.ids(); }
-    has(id) { return this.bindings.has(id); }
-    get(id) { return this.bindings.get(id); }
-    require(id) { return this.bindings.require(id); }
-    values() { return this.bindings.values(); }
-    entries() { return this.bindings.entries(); }
-    identity(id) { return this.require(id).identity; }
+    /** Registered bindings in declaration order, with methods already bound to their owner. */
+    get definitions() {
+        return Object.freeze([...this.bindings.values()]);
+    }
+    /** Registered binding ids in declaration order. */
+    ids() {
+        return this.bindings.ids();
+    }
+    /** Whether a binding id is registered. */
+    has(id) {
+        return this.bindings.has(id);
+    }
+    /** Registered binding for `id`, or `undefined` when it is absent. */
+    get(id) {
+        return this.bindings.get(id);
+    }
+    /**
+     * Registered binding for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    require(id) {
+        return this.bindings.require(id);
+    }
+    /** Iterate the registered bindings. */
+    values() {
+        return this.bindings.values();
+    }
+    /** Iterate `[id, binding]` pairs. */
+    entries() {
+        return this.bindings.entries();
+    }
+    /**
+     * Implementation identity of one binding.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    identity(id) {
+        return this.require(id).identity;
+    }
     async invoke(request, context) {
         if (!request || typeof request !== 'object' || !('input' in request))
             throw new TypeError('Use one model request and execution context');
         const { modelId: id, input, timeoutMs } = request;
-        if (!context?.signal || typeof id !== 'string' || !id.trim() || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)
+        if (!context?.signal ||
+            typeof id !== 'string' ||
+            !id.trim() ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs < 1 ||
+            // 2147483647 is the largest delay `setTimeout`/`AbortSignal.timeout` accept reliably.
+            timeoutMs > 2147483647)
             throw new TypeError('A modelId, signal and positive supported timeoutMs are required');
         const sourceBudget = context.attemptBudget;
         const take = sourceBudget?.take.bind(sourceBudget);
         const callId = (0, invocation_js_1.invocationId)(), startedAtMs = Date.now();
-        const diagnostics = context.diagnostics?.child(callId, { invocationId: callId, modelId: id, nodeRole: 'invocation', definitionKind: 'model-binding', definitionId: id, nodeId: id, nodeName: id, nodeKind: 'model-binding' });
+        const diagnostics = context.diagnostics?.child(callId, {
+            invocationId: callId,
+            modelId: id,
+            nodeRole: 'invocation',
+            definitionKind: 'model-binding',
+            definitionId: id,
+            nodeId: id,
+            nodeName: id,
+            nodeKind: 'model-binding',
+        });
         const signal = (0, cancellation_js_1.combineSignals)(context.signal, AbortSignal.timeout(timeoutMs));
         let phase = 'input';
         try {
@@ -51,7 +113,12 @@ class ModelCalls {
             }
             const callSequence = ++this.sequence;
             phase = 'invoke';
-            diagnostics?.emit('model.binding', () => ({ modelId: id, invocationId: callId, status: 'running', phase }));
+            diagnostics?.emit('model.binding', () => ({
+                modelId: id,
+                invocationId: callId,
+                status: 'running',
+                phase,
+            }));
             // Hand off checked inputs before yielding. Arbitrary App inputs may be
             // class instances or services, so Core must not silently clone them.
             signal.throwIfAborted();
@@ -60,11 +127,32 @@ class ModelCalls {
             phase = 'output';
             (0, synchronous_js_1.assertion)(binding.assertOutput?.(output), 'Model output assertions must be synchronous');
             signal.throwIfAborted();
-            diagnostics?.emit('model.binding', () => ({ modelId: id, invocationId: callId, status: 'success', phase, durationMs: Date.now() - startedAtMs }));
-            return (0, invocation_js_1.invocationResult)(output, { ...diagnostics?.identity, invocationId: callId, modelId: id, startedAtMs, durationMs: Date.now() - startedAtMs, callSequence, status: 'success' });
+            diagnostics?.emit('model.binding', () => ({
+                modelId: id,
+                invocationId: callId,
+                status: 'success',
+                phase,
+                durationMs: Date.now() - startedAtMs,
+            }));
+            return (0, invocation_js_1.invocationResult)(output, {
+                ...diagnostics?.identity,
+                invocationId: callId,
+                modelId: id,
+                startedAtMs,
+                durationMs: Date.now() - startedAtMs,
+                callSequence,
+                status: 'success',
+            });
         }
         catch (error) {
-            diagnostics?.emit('model.binding', () => ({ modelId: id, invocationId: callId, status: signal.aborted ? 'cancelled' : 'error', phase, durationMs: Date.now() - startedAtMs, errorCode: (0, errors_js_2.getErrorInfo)(error).code }));
+            diagnostics?.emit('model.binding', () => ({
+                modelId: id,
+                invocationId: callId,
+                status: signal.aborted ? 'cancelled' : 'error',
+                phase,
+                durationMs: Date.now() - startedAtMs,
+                errorCode: (0, errors_js_2.getErrorInfo)(error).code,
+            }));
             throw error;
         }
     }

package/dist/cjs/kits/intents/catalog.js

@@ -1,31 +1,82 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineAgentCatalog = defineAgentCatalog;
+/**
+ * Intents Kit: project registered intents, scopes and tools into one task-facing catalog.
+ *
+ * Place in the package: part of the `intents` Kit. It reads the actual registries supplied by
+ * the App instead of maintaining a parallel capability list, so an intent is only advertised
+ * when its tools, scopes and availability agree.
+ *
+ * Exports: `defineAgentCatalog`, and the catalog intent/scope/port types.
+ */
 const synchronous_js_1 = require("../../utils/synchronous.js");
-/** The actual registries determine availability and relationships. No parallel capability list. */
+/**
+ * Compile a catalog projection over the App's live registries.
+ *
+ * The actual registries determine availability and relationships. No parallel capability list
+ * exists: `intentIds` filters by tool support, `modelCatalog` narrows to the currently accepted
+ * task when `restrictToTask` is enabled, and scope tool ids are filtered to tools that exist.
+ *
+ * @param ports - Sources for intent ids, intents, scopes, the current task, the tool registry
+ *   and the `restrictToTask` switch.
+ * @returns A frozen projection with `intentIds`, `intentSteps`, `intentCatalog`,
+ *   `scopeCatalog` and `modelCatalog`.
+ * @throws TypeError When a supplied predicate does not return a boolean synchronously.
+ */
 function defineAgentCatalog(ports) {
     const ids = ports.intentIds.bind(ports), intents = ports.intents.bind(ports), scopes = ports.scopes.bind(ports), task = ports.currentTask.bind(ports);
-    const tools = { values: ports.tools.values.bind(ports.tools), has: ports.tools.has.bind(ports.tools), supports: ports.tools.supportsIntent.bind(ports.tools), describe: ports.tools.describe.bind(ports.tools) };
+    const tools = {
+        values: ports.tools.values.bind(ports.tools),
+        has: ports.tools.has.bind(ports.tools),
+        supports: ports.tools.supportsIntent.bind(ports.tools),
+        describe: ports.tools.describe.bind(ports.tools),
+    };
     const restrict = ports.restrictToTask !== false;
     const boolean = (value) => (0, synchronous_js_1.booleanResult)(value, 'Catalog predicates must be synchronous', 'Catalog predicates must return boolean');
-    const intentIds = (app) => ids().filter(id => boolean(tools.supports(id, app)));
-    const intentSteps = (app) => new Map(intents().map(intent => [intent.id, [...new Set([
-                ...intent.steps, ...[...tools.values()].filter(tool => tool.invocation && (!tool.available || app === undefined || boolean(tool.available(app)))
-                    && (tool.intentIds === 'all' || tool.intentIds.includes(intent.id))).map(tool => tool.invocation.step),
-            ])]]));
+    const intentIds = (app) => ids().filter((id) => boolean(tools.supports(id, app)));
+    const intentSteps = (app) => new Map(intents().map((intent) => [
+        intent.id,
+        [
+            ...new Set([
+                ...intent.steps,
+                ...[...tools.values()]
+                    .filter((tool) => tool.invocation &&
+                    (!tool.available || app === undefined || boolean(tool.available(app))) &&
+                    (tool.intentIds === 'all' || tool.intentIds.includes(intent.id)))
+                    .map((tool) => tool.invocation.step),
+            ]),
+        ],
+    ]));
     const intentCatalog = (app) => {
         const selected = intentIds(app), described = tools.describe('model', app), steps = intentSteps(app);
-        return intents(selected).map(intent => ({ ...intent, steps: steps.get(intent.id) ?? [...intent.steps],
-            scopeIds: scopes([intent.id]).map(scope => scope.id), toolIds: described.filter(tool => tool.intentIds.includes(intent.id)).map(tool => tool.id) }));
+        return intents(selected).map((intent) => ({
+            ...intent,
+            steps: steps.get(intent.id) ?? [...intent.steps],
+            scopeIds: scopes([intent.id]).map((scope) => scope.id),
+            toolIds: described
+                .filter((tool) => tool.intentIds.includes(intent.id))
+                .map((tool) => tool.id),
+        }));
     };
-    const scopeCatalog = (app) => scopes(intentIds(app)).map(scope => ({ ...scope, toolIds: scope.toolIds.filter(tools.has) }));
-    return Object.freeze({ intentIds, intentSteps, intentCatalog, scopeCatalog,
+    const scopeCatalog = (app) => scopes(intentIds(app)).map((scope) => ({ ...scope, toolIds: scope.toolIds.filter(tools.has) }));
+    return Object.freeze({
+        intentIds,
+        intentSteps,
+        intentCatalog,
+        scopeCatalog,
         modelCatalog(app) {
-            const accepted = restrict ? task(app) : undefined, selected = intentIds(app).filter(id => !accepted || id === accepted.intentId);
-            return { availableIntentIds: selected,
-                availableIntents: intentCatalog(app).filter(intent => selected.includes(intent.id)).map(intent => accepted ? { ...intent, scopeIds: accepted.scopeId ? [accepted.scopeId] : [] } : intent),
-                availableScopes: scopeCatalog(app).filter(scope => !accepted || scope.id === accepted.scopeId),
-                availableTools: tools.describe('model', app).filter(tool => !accepted || tool.intentIds.includes(accepted.intentId)) };
+            const accepted = restrict ? task(app) : undefined, selected = intentIds(app).filter((id) => !accepted || id === accepted.intentId);
+            return {
+                availableIntentIds: selected,
+                availableIntents: intentCatalog(app)
+                    .filter((intent) => selected.includes(intent.id))
+                    .map((intent) => accepted ? { ...intent, scopeIds: accepted.scopeId ? [accepted.scopeId] : [] } : intent),
+                availableScopes: scopeCatalog(app).filter((scope) => !accepted || scope.id === accepted.scopeId),
+                availableTools: tools
+                    .describe('model', app)
+                    .filter((tool) => !accepted || tool.intentIds.includes(accepted.intentId)),
+            };
         },
     });
 }

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

@@ -15,10 +15,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Intents = void 0;
+/**
+ * Intents Kit entry: intent and scope registries plus the task-facing catalog projection.
+ *
+ * Place in the package: an optional App-side library for declaring what the agent may do.
+ * Applications register their own intents and scopes; this directory owns registration
+ * checks, aliases, relationship lookups and the model-visible projection. Core never imports it.
+ *
+ * Exports: everything from `./registry.js`, `./scopes.js` and `./catalog.js`, plus the
+ * `Intents` namespace object.
+ */
 __exportStar(require("./registry.js"), exports);
 __exportStar(require("./scopes.js"), exports);
 __exportStar(require("./catalog.js"), exports);
 const registry_js_1 = require("./registry.js");
 const scopes_js_1 = require("./scopes.js");
 const catalog_js_1 = require("./catalog.js");
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.Intents = Object.freeze({ IntentRegistry: registry_js_1.IntentRegistry, ScopeRegistry: scopes_js_1.ScopeRegistry, defineAgentCatalog: catalog_js_1.defineAgentCatalog });