@jangts/agent-core 0.1.1 → 0.2.1

package/dist/cjs/kits/search.js

@@ -4,64 +4,188 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TextSearch = void 0;
+/**
+ * Text Search Kit: an in-memory MiniSearch index with explicit field declarations.
+ *
+ * Place in the package: an optional App-side full-text index. The Kit owns the index,
+ * declarative validation and snapshot compatibility; corpus, tokenization policy, storage,
+ * identity, filters and persistence stay with the App. No model call or Core dependency is
+ * involved, and nothing is written to disk here.
+ *
+ * Exports: `TextSearch` and the search option/query/hit/snapshot types.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const minisearch_1 = __importDefault(require("minisearch"));
 const rules_js_1 = require("../utils/rules.js");
-/** Optional App-side full-text index. No storage, identity, model calls or Core dependencies. */
+/**
+ * Optional App-side full-text index. No storage, identity, model calls or Core dependencies.
+ *
+ * Only declared fields are indexed and only `storedFields` come back with a hit, so a document
+ * never leaks extra properties into search results.
+ */
 class TextSearch {
     options;
     stored;
     inputFields;
     configurationFingerprint;
     index;
+    /**
+     * Compile the index configuration and validate it before any document is added.
+     *
+     * @param registration - Format revision, indexed and stored fields, optional tokenizer,
+     *   boosts and combination mode; handlers are bound to this object.
+     * @throws TypeError For a missing revision, empty/duplicate/blank field declarations, stored
+     *   fields that collide with search metadata, an invalid tokenizer or combination, or a
+     *   boost for an undeclared field or with a non-positive value.
+     */
     constructor(registration) {
-        const definition = { indexRevision: registration.indexRevision, fields: registration.fields, storedFields: registration.storedFields,
-            tokenize: registration.tokenize, boost: registration.boost, combineWith: registration.combineWith };
+        const definition = {
+            indexRevision: registration.indexRevision,
+            fields: registration.fields,
+            storedFields: registration.storedFields,
+            tokenize: registration.tokenize,
+            boost: registration.boost,
+            combineWith: registration.combineWith,
+        };
         const reserved = new Set(['id', 'score', 'terms', 'queryTerms', 'match']);
         (0, rules_js_1.breakWhile)([
-            { occur: () => !definition || typeof definition.indexRevision !== 'string' || !definition.indexRevision.trim(), error: 'Text search requires an application format revision' },
-            { occur: () => !Array.isArray(definition.fields) || !definition.fields.length || !Array.isArray(definition.storedFields), error: 'Text search requires field declarations' },
-            { occur: () => [...definition.fields, ...definition.storedFields].some(f => typeof f !== 'string' || !f.trim()), error: 'Invalid text search field' },
-            { occur: () => new Set(definition.fields).size !== definition.fields.length || new Set(definition.storedFields).size !== definition.storedFields.length, error: 'Duplicate text search field' },
-            { occur: () => definition.storedFields.some(f => reserved.has(f)), error: 'Stored fields conflict with search metadata' },
-            { occur: () => definition.tokenize !== undefined && typeof definition.tokenize !== 'function', error: 'Invalid text search tokenizer' },
-            { occur: () => definition.combineWith !== undefined && !['AND', 'OR'].includes(definition.combineWith), error: 'Invalid text search combination' },
-            { occur: () => Object.entries(definition.boost ?? {}).some(([field, value]) => !definition.fields.includes(field) || typeof value !== 'number' || !Number.isFinite(value) || value <= 0), error: 'Invalid text search field boost' },
+            {
+                occur: () => !definition ||
+                    typeof definition.indexRevision !== 'string' ||
+                    !definition.indexRevision.trim(),
+                error: 'Text search requires an application format revision',
+            },
+            {
+                occur: () => !Array.isArray(definition.fields) ||
+                    !definition.fields.length ||
+                    !Array.isArray(definition.storedFields),
+                error: 'Text search requires field declarations',
+            },
+            {
+                occur: () => [...definition.fields, ...definition.storedFields].some((f) => typeof f !== 'string' || !f.trim()),
+                error: 'Invalid text search field',
+            },
+            {
+                occur: () => new Set(definition.fields).size !== definition.fields.length ||
+                    new Set(definition.storedFields).size !== definition.storedFields.length,
+                error: 'Duplicate text search field',
+            },
+            {
+                occur: () => definition.storedFields.some((f) => reserved.has(f)),
+                error: 'Stored fields conflict with search metadata',
+            },
+            {
+                occur: () => definition.tokenize !== undefined && typeof definition.tokenize !== 'function',
+                error: 'Invalid text search tokenizer',
+            },
+            {
+                occur: () => definition.combineWith !== undefined && !['AND', 'OR'].includes(definition.combineWith),
+                error: 'Invalid text search combination',
+            },
+            {
+                occur: () => Object.entries(definition.boost ?? {}).some(([field, value]) => !definition.fields.includes(field) ||
+                    typeof value !== 'number' ||
+                    !Number.isFinite(value) ||
+                    value <= 0),
+                error: 'Invalid text search field boost',
+            },
         ], ['kit', 'text-search', 'registration']);
         this.stored = Object.freeze([...definition.storedFields]);
         this.inputFields = Object.freeze([...new Set([...definition.fields, ...this.stored])]);
         // Object entries have distinct keys, so there is no equal-key ordering case.
-        const boost = Object.fromEntries(Object.entries(definition.boost ?? {}).sort(([a], [b]) => a < b ? -1 : 1));
-        this.options = { fields: [...definition.fields], storeFields: [...definition.storedFields], ...(definition.tokenize ? { tokenize: definition.tokenize.bind(registration) } : {}),
-            searchOptions: { boost, combineWith: definition.combineWith ?? 'OR' } };
-        this.configurationFingerprint = JSON.stringify({ indexRevision: definition.indexRevision, fields: this.options.fields, storedFields: this.options.storeFields, boost: this.options.searchOptions.boost, combineWith: this.options.searchOptions.combineWith });
+        const boost = Object.fromEntries(Object.entries(definition.boost ?? {}).sort(([a], [b]) => (a < b ? -1 : 1)));
+        this.options = {
+            fields: [...definition.fields],
+            storeFields: [...definition.storedFields],
+            ...(definition.tokenize ? { tokenize: definition.tokenize.bind(registration) } : {}),
+            searchOptions: { boost, combineWith: definition.combineWith ?? 'OR' },
+        };
+        this.configurationFingerprint = JSON.stringify({
+            indexRevision: definition.indexRevision,
+            fields: this.options.fields,
+            storedFields: this.options.storeFields,
+            boost: this.options.searchOptions.boost,
+            combineWith: this.options.searchOptions.combineWith,
+        });
         this.index = new minisearch_1.default(this.options);
     }
+    /**
+     * Insert or replace one document.
+     *
+     * @param document - Document carrying a non-blank string `id`; only declared fields are kept.
+     * @throws TypeError For a missing document, a blank/non-string id, or a non-string value in
+     *   an indexed field.
+     */
     upsert(document) {
         (0, rules_js_1.breakWhile)(!document, 'Invalid text search document');
         // Only declared fields belong to this index. Read inherited getters before
         // cloning and do not retain caller-owned nested metadata or extra services.
-        const snapshot = structuredClone({ ...Object.fromEntries(this.inputFields.map(field => [field, document[field]])), id: document.id });
-        (0, rules_js_1.breakWhile)(typeof snapshot.id !== 'string' || !snapshot.id.trim() || this.options.fields.some(field => snapshot[field] !== undefined && typeof snapshot[field] !== 'string'), 'Invalid text search document');
+        const snapshot = structuredClone({
+            ...Object.fromEntries(this.inputFields.map((field) => [field, document[field]])),
+            id: document.id,
+        });
+        (0, rules_js_1.breakWhile)(typeof snapshot.id !== 'string' ||
+            !snapshot.id.trim() ||
+            this.options.fields.some((field) => snapshot[field] !== undefined && typeof snapshot[field] !== 'string'), 'Invalid text search document');
         if (this.index.has(snapshot.id))
             this.index.replace(snapshot);
         else
             this.index.add(snapshot);
     }
+    /**
+     * Search the index and return at most `limit` hits.
+     *
+     * @param options - Non-empty query text, limit (1..1000) and a synchronous filter that decides
+     *   which stored documents may be returned.
+     * @returns Hits ordered by MiniSearch relevance, carrying the stored fields only.
+     * @throws TypeError For a blank query, an out-of-range limit, a missing filter, a filter
+     *   result that is not synchronous boolean.
+     */
     search(options) {
         const { query } = options;
         (0, rules_js_1.breakWhile)([
-            { occur: () => typeof query !== 'string' || !query.trim(), error: 'Text search requires a nonempty query' },
-            { occur: () => !options || !Number.isSafeInteger(options.limit) || options.limit < 1 || options.limit > 1000, error: 'Text search limit must be between 1 and 1000' },
-            { occur: () => typeof options.filter !== 'function', error: 'Text search requires an application filter' },
+            {
+                occur: () => typeof query !== 'string' || !query.trim(),
+                error: 'Text search requires a nonempty query',
+            },
+            {
+                occur: () => !options ||
+                    !Number.isSafeInteger(options.limit) ||
+                    options.limit < 1 ||
+                    options.limit > 1000,
+                error: 'Text search limit must be between 1 and 1000',
+            },
+            {
+                occur: () => typeof options.filter !== 'function',
+                error: 'Text search requires an application filter',
+            },
         ], ['kit', 'text-search', 'query']);
-        return this.index.search(query, { filter: hit => (0, synchronous_js_1.booleanResult)(options.filter({ ...this.fields(hit), id: String(hit.id) }), 'Text search filters must be synchronous', 'Text search filters must return boolean') }).slice(0, options.limit)
-            .map(hit => ({ id: String(hit.id), score: hit.score, terms: [...hit.terms], document: this.fields(hit) }));
+        return this.index
+            .search(query, {
+            filter: (hit) => (0, synchronous_js_1.booleanResult)(options.filter({ ...this.fields(hit), id: String(hit.id) }), 'Text search filters must be synchronous', 'Text search filters must return boolean'),
+        })
+            .slice(0, options.limit)
+            .map((hit) => ({
+            id: String(hit.id),
+            score: hit.score,
+            terms: [...hit.terms],
+            document: this.fields(hit),
+        }));
     }
     fields(hit) {
-        return structuredClone(Object.fromEntries(this.stored.filter(field => Object.hasOwn(hit, field)).map(field => [field, hit[field]])));
+        return structuredClone(Object.fromEntries(this.stored
+            .filter((field) => Object.hasOwn(hit, field))
+            .map((field) => [field, hit[field]])));
     }
-    /** Vacuum before returning so deleted terms do not survive the next serialized checkpoint. */
+    /**
+     * Remove one document.
+     *
+     * Vacuum before returning so deleted terms do not survive the next serialized checkpoint.
+     *
+     * @param id - Document id; a non-blank string is required.
+     * @returns Whether a document was actually discarded.
+     * @throws TypeError For a blank or non-string id.
+     */
     async remove(id) {
         (0, rules_js_1.breakWhile)(typeof id !== 'string' || !id.trim(), 'Invalid text search document id');
         if (!this.index.has(id))
@@ -70,11 +194,40 @@ class TextSearch {
         await this.index.vacuum();
         return true;
     }
-    clear() { this.index.removeAll(); }
-    snapshot() { return { version: 2, engine: 'minisearch-7', configurationFingerprint: this.configurationFingerprint, serializedIndex: JSON.stringify(this.index) }; }
+    /** Drop every document while keeping the compiled configuration. */
+    clear() {
+        this.index.removeAll();
+    }
+    /**
+     * Serialize the index together with the configuration used to build it.
+     *
+     * @returns A versioned snapshot; the fingerprint lets `restore` reject a mismatched setup.
+     */
+    snapshot() {
+        return {
+            // The layout version and engine tag pin the serialized format to MiniSearch 7 semantics.
+            version: 2,
+            engine: 'minisearch-7',
+            configurationFingerprint: this.configurationFingerprint,
+            serializedIndex: JSON.stringify(this.index),
+        };
+    }
+    /**
+     * Rebuild an index from a snapshot.
+     *
+     * @param definition - The same configuration the snapshot was produced with.
+     * @param snapshot - Snapshot returned by `snapshot`.
+     * @returns A new populated `TextSearch`.
+     * @throws An error when the layout version, engine tag, configuration fingerprint or payload
+     *   type does not match, because restoring an incompatible index would silently misanswer.
+     */
     static restore(definition, snapshot) {
         const search = new TextSearch(definition);
-        (0, rules_js_1.breakWhile)(!snapshot || snapshot.version !== 2 || snapshot.engine !== 'minisearch-7' || snapshot.configurationFingerprint !== search.configurationFingerprint || typeof snapshot.serializedIndex !== 'string', 'Incompatible text search snapshot; rebuild from application records');
+        (0, rules_js_1.breakWhile)(!snapshot ||
+            snapshot.version !== 2 ||
+            snapshot.engine !== 'minisearch-7' ||
+            snapshot.configurationFingerprint !== search.configurationFingerprint ||
+            typeof snapshot.serializedIndex !== 'string', 'Incompatible text search snapshot; rebuild from application records');
         search.index = minisearch_1.default.loadJSON(snapshot.serializedIndex, search.options);
         return search;
     }

package/dist/cjs/kits/text-skills.js

@@ -2,21 +2,57 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TextSkills = void 0;
 exports.defineTextSkillLoader = defineTextSkillLoader;
+/**
+ * Text Skills Kit: compile declarative, text-only skill registrations into readable skills.
+ *
+ * Place in the package: an optional App-side library for skill documents that are pure text.
+ * Documents are read through an App port; nothing here executes code, imports modules, binds
+ * tools or grants authority. Tool ids are only carried as declared references.
+ *
+ * Exports: `defineTextSkillLoader`, `TextSkills`, and the skill document/port types.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
-/** Compile text-only skill rules. Hosts supply document reads; no code, tools or imports execute here. */
+/**
+ * Compile a loader that validates registrations and reads their documents.
+ *
+ * The default contract is narrow by design: ids are lower-case words joined by hyphens (up to
+ * `maxIdChars`, default 64), each entry lives at `<id>/SKILL.md`, the kind is `text-workflow`,
+ * and the document starts with `name`/`description` front matter.
+ *
+ * @param definition - Size limits, optional per-app entry/header overrides and error wording;
+ *   handlers are bound to this object.
+ * @returns A frozen loader with `load({ entries }, ports)`.
+ * @throws TypeError At construction for non-integer or non-positive limits; from `load` for a
+ *   malformed catalog, duplicate/invalid ids, a mismatched entry path or kind, duplicate tool
+ *   ids, an oversized instruction body, or a header that is absent or disagrees with the id.
+ */
 function defineTextSkillLoader(definition) {
     const { maxInstructionChars, maxDescriptionChars, maxIdChars = 64 } = definition;
     (0, rules_js_1.breakWhile)([
-        { occur: () => ![maxInstructionChars, maxDescriptionChars, maxIdChars].every(Number.isSafeInteger), error: 'Invalid text skill limits', tags: ['integer'] },
-        { occur: () => Math.min(maxInstructionChars, maxDescriptionChars, maxIdChars) < 1, error: 'Invalid text skill limits', tags: ['range'] },
+        {
+            occur: () => ![maxInstructionChars, maxDescriptionChars, maxIdChars].every(Number.isSafeInteger),
+            error: 'Invalid text skill limits',
+            tags: ['integer'],
+        },
+        {
+            occur: () => Math.min(maxInstructionChars, maxDescriptionChars, maxIdChars) < 1,
+            error: 'Invalid text skill limits',
+            tags: ['range'],
+        },
     ]);
     const idPattern = new RegExp(`^[a-z][a-z0-9-]{0,${maxIdChars - 1}}$`);
-    const entryFor = definition.entryFor?.bind(definition) ?? (id => `${id}/SKILL.md`);
+    const entryFor = definition.entryFor?.bind(definition) ?? ((id) => `${id}/SKILL.md`);
     const parseHeader = definition.parseHeader?.bind(definition) ?? strictHeader;
-    const catalogError = (typeof definition.errors?.catalog === 'function' ? definition.errors.catalog.bind(definition.errors) : definition.errors?.catalog) ?? 'Text skill catalog must be an array';
-    const registrationError = (typeof definition.errors?.registration === 'function' ? definition.errors.registration.bind(definition.errors) : definition.errors?.registration) ?? 'Invalid text skill registration';
-    const documentError = (typeof definition.errors?.document === 'function' ? definition.errors.document.bind(definition.errors) : definition.errors?.document) ?? 'Invalid text skill document';
+    const catalogError = (typeof definition.errors?.catalog === 'function'
+        ? definition.errors.catalog.bind(definition.errors)
+        : definition.errors?.catalog) ?? 'Text skill catalog must be an array';
+    const registrationError = (typeof definition.errors?.registration === 'function'
+        ? definition.errors.registration.bind(definition.errors)
+        : definition.errors?.registration) ?? 'Invalid text skill registration';
+    const documentError = (typeof definition.errors?.document === 'function'
+        ? definition.errors.document.bind(definition.errors)
+        : definition.errors?.document) ?? 'Invalid text skill document';
     const tags = [...(definition.tags ?? [])];
     return Object.freeze({
         load(input, ports) {
@@ -24,16 +60,49 @@ function defineTextSkillLoader(definition) {
             const entries = input.entries, read = ports.read.bind(ports);
             (0, rules_js_1.breakWhile)(!Array.isArray(entries), catalogError);
             const ids = new Set();
-            return Object.freeze(entries.map(raw => {
-                (0, rules_js_1.breakWhile)(!raw || typeof raw !== 'object' || Array.isArray(raw), registrationError, [...tags, 'registration', 'shape']);
-                const entry = { id: raw.id, entry: raw.entry, kind: raw.kind, toolIds: raw.toolIds };
+            return Object.freeze(entries.map((raw) => {
+                (0, rules_js_1.breakWhile)(!raw || typeof raw !== 'object' || Array.isArray(raw), registrationError, [
+                    ...tags,
+                    'registration',
+                    'shape',
+                ]);
+                const entry = {
+                    id: raw.id,
+                    entry: raw.entry,
+                    kind: raw.kind,
+                    toolIds: raw.toolIds,
+                };
                 (0, rules_js_1.breakWhile)([
-                    { occur: () => !entry || typeof entry !== 'object', error: registrationError, tags: ['shape'] },
-                    { occur: [() => typeof entry.id !== 'string' || !idPattern.test(entry.id), () => ids.has(entry.id)], error: registrationError, tags: ['id'] },
-                    { occur: [() => entry.entry !== (0, synchronous_js_1.synchronous)(entryFor(entry.id), 'Skill entry selectors must be synchronous'), () => entry.kind !== 'text-workflow'], error: registrationError, tags: ['workflow'] },
                     {
-                        occur: [() => !Array.isArray(entry.toolIds), () => entry.toolIds.some(tool => typeof tool !== 'string' || !tool), () => new Set(entry.toolIds).size !== entry.toolIds.length],
-                        error: registrationError, tags: ['tools'],
+                        occur: () => !entry || typeof entry !== 'object',
+                        error: registrationError,
+                        tags: ['shape'],
+                    },
+                    {
+                        occur: [
+                            () => typeof entry.id !== 'string' || !idPattern.test(entry.id),
+                            () => ids.has(entry.id),
+                        ],
+                        error: registrationError,
+                        tags: ['id'],
+                    },
+                    {
+                        occur: [
+                            () => entry.entry !==
+                                (0, synchronous_js_1.synchronous)(entryFor(entry.id), 'Skill entry selectors must be synchronous'),
+                            () => entry.kind !== 'text-workflow',
+                        ],
+                        error: registrationError,
+                        tags: ['workflow'],
+                    },
+                    {
+                        occur: [
+                            () => !Array.isArray(entry.toolIds),
+                            () => entry.toolIds.some((tool) => typeof tool !== 'string' || !tool),
+                            () => new Set(entry.toolIds).size !== entry.toolIds.length,
+                        ],
+                        error: registrationError,
+                        tags: ['tools'],
                     },
                 ], [...tags, 'registration']);
                 ids.add(entry.id);
@@ -41,17 +110,33 @@ function defineTextSkillLoader(definition) {
                 (0, rules_js_1.breakWhile)(typeof instructions !== 'string' || instructions.length > maxInstructionChars, documentError, [...tags, 'document', 'instructions']);
                 const header = (0, synchronous_js_1.synchronous)(parseHeader(instructions), 'Skill header parsing must be synchronous');
                 (0, rules_js_1.breakWhile)([
-                    { occur: [() => !header, () => header.id !== entry.id], error: documentError, tags: ['identity'] },
-                    { occur: () => !header.description.trim() || header.description.length > maxDescriptionChars, error: documentError, tags: ['description'] },
+                    {
+                        occur: [() => !header, () => header.id !== entry.id],
+                        error: documentError,
+                        tags: ['identity'],
+                    },
+                    {
+                        occur: () => !header.description.trim() || header.description.length > maxDescriptionChars,
+                        error: documentError,
+                        tags: ['description'],
+                    },
                 ], [...tags, 'document']);
-                return Object.freeze({ id: entry.id, entry: entry.entry, kind: entry.kind, toolIds: Object.freeze([...entry.toolIds]),
-                    description: header.description.trim(), instructions });
+                return Object.freeze({
+                    id: entry.id,
+                    entry: entry.entry,
+                    kind: entry.kind,
+                    toolIds: Object.freeze([...entry.toolIds]),
+                    description: header.description.trim(),
+                    instructions,
+                });
             }));
         },
     });
 }
+/** Default header parser: exactly the two front-matter keys, nothing else, in this order. */
 function strictHeader(instructions) {
     const header = instructions.match(/^---\r?\nname: ([a-z][a-z0-9-]*)\r?\ndescription: ([^\r\n]+)\r?\n---(?:\r?\n|$)/);
     return header ? { id: header[1], description: header[2] } : undefined;
 }
+/** Namespace object for callers that prefer one import over named helpers. */
 exports.TextSkills = Object.freeze({ defineTextSkillLoader });