@mcp-abap-adt/llm-agent-server-libs 19.1.2 → 19.2.0

package/dist/smart-agent/jsonl-knowledge-backend.js

@@ -1,10 +1,12 @@
 import { appendFile, mkdir, readFile, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { matchesKnowledgeFilter, } from '@mcp-abap-adt/llm-agent-libs';
 export class JsonlKnowledgeBackend {
     logDir;
     semantic;
     constructor(logDir, 
-    /** Optional semantic index for query(); when absent, query falls back to recency. */
+    /** Optional semantic index; when present query() ranks by similarity and the
+     *  index is lazily rehydrated from the durable JSONL on first use. */
     semantic) {
         this.logDir = logDir;
         this.semantic = semantic;
@@ -12,16 +14,80 @@ export class JsonlKnowledgeBackend {
     file(sid) {
         return join(this.logDir, 'sessions', sid, 'knowledge.jsonl');
     }
-    async put(sid, entry) {
+    // The in-process index is EMPTY after a restart, but the JSONL log is durable, so
+    // it is REBUILT from the durable scan on first use per session. Every
+    // index-touching op (build / put / query / delete) runs through run(sid, ...) — a
+    // per-session promise chain — so none interleaves; the chain entry is dropped once
+    // it drains so the Map cannot grow unbounded. `built` records ONLY successful
+    // builds so a failed scan/embed retries rather than caching a rejection.
+    built = new Set();
+    chain = new Map();
+    run(sid, fn) {
+        const prev = this.chain.get(sid) ?? Promise.resolve();
+        const next = prev.then(fn, fn); // run regardless of prior outcome
+        const tail = next.then(() => { }, () => { });
+        this.chain.set(sid, tail);
+        void tail.then(() => {
+            if (this.chain.get(sid) === tail)
+                this.chain.delete(sid);
+        });
+        return next;
+    }
+    /** Lazy rehydration of the in-process index from the durable JSONL. `options`
+     *  is forwarded into every re-index `upsert` so the embedder receives the
+     *  triggering request's requestLogger — the lazy rebuild's embedding cost is
+     *  metered against the request that triggered it (not silently dropped). */
+    async build(sid, options) {
+        if (!this.semantic || this.built.has(sid))
+            return;
+        this.semantic.deleteSession(sid); // clear any partial state → idempotent
+        for (const e of await this.scan(sid))
+            await this.semantic.upsert(sid, e, options);
+        this.built.add(sid); // mark built ONLY on success
+    }
+    async append(sid, entry) {
         const f = this.file(sid);
         await mkdir(dirname(f), { recursive: true });
         await appendFile(f, `${JSON.stringify(entry)}\n`, 'utf8');
-        await this.semantic?.upsert(sid, entry);
     }
-    async semanticQuery(sid, text, k) {
-        if (this.semantic)
-            return this.semantic.query(sid, text, k);
-        const all = await this.scan(sid);
+    async put(sid, entry, options) {
+        if (!this.semantic) {
+            await this.append(sid, entry);
+            return;
+        }
+        // ENTIRE put serialized: build FIRST (indexes the durable JSONL BEFORE this
+        // append → the new entry is never double-counted by a rebuild scan), THEN
+        // append, THEN upsert once. A durable append is the success point: an index
+        // upsert failure does NOT rethrow (that would make the caller retry put() and
+        // append the same artifact twice); instead mark the session dirty so the next
+        // build re-syncs from the durable JSONL.
+        await this.run(sid, async () => {
+            await this.build(sid, options);
+            await this.append(sid, entry);
+            try {
+                await this.semantic?.upsert(sid, entry, options);
+            }
+            catch (e) {
+                this.built.delete(sid);
+                if (process.env.DEBUG_CONTROLLER)
+                    console.error(`[jsonl-index] upsert failed (will rebuild lazily): ${String(e)}`);
+            }
+        });
+    }
+    async semanticQuery(sid, text, k, filter, options) {
+        if (this.semantic) {
+            // build + query in ONE run() so the query reads a consistent snapshot.
+            // options is captured in closure and forwarded into the index query so the
+            // embedder receives requestLogger for token metering.
+            return this.run(sid, async () => {
+                await this.build(sid, options);
+                // biome-ignore lint/style/noNonNullAssertion: guarded by the outer check
+                return this.semantic.query(sid, text, k, filter, options);
+            });
+        }
+        let all = await this.scan(sid);
+        if (filter)
+            all = all.filter((e) => matchesKnowledgeFilter(e.metadata, filter));
         return k ? all.slice(-k) : all;
     }
     async scan(sid) {
@@ -39,8 +105,14 @@ export class JsonlKnowledgeBackend {
         }
     }
     async deleteSession(sid) {
-        // Remove the whole per-session directory (knowledge.jsonl + any siblings).
-        await rm(dirname(this.file(sid)), { recursive: true, force: true });
+        await this.run(sid, async () => {
+            await rm(dirname(this.file(sid)), { recursive: true, force: true });
+            this.semantic?.deleteSession(sid);
+            this.built.delete(sid);
+        });
+    }
+    get semanticRecallCapable() {
+        return this.semantic !== undefined;
     }
 }
 //# sourceMappingURL=jsonl-knowledge-backend.js.map

package/dist/smart-agent/jsonl-knowledge-backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonl-knowledge-backend.js","sourceRoot":"","sources":["../../src/smart-agent/jsonl-knowledge-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAI1C,MAAM,OAAO,qBAAqB;IAEb;IAEA;IAHnB,YACmB,MAAc;IAC/B,qFAAqF;IACpE,QAOhB;QATgB,WAAM,GAAN,MAAM,CAAQ;QAEd,aAAQ,GAAR,QAAQ,CAOxB;IACA,CAAC;IAEI,IAAI,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAqB;QAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,MAAM,UAAU,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC1D,MAAM,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,GAAW,EACX,IAAY,EACZ,CAAU;QAEV,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YACnD,OAAO,GAAG;iBACP,KAAK,CAAC,IAAI,CAAC;iBACX,MAAM,CAAC,OAAO,CAAC;iBACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAmB,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAK,CAA2B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,EAAE,CAAC;YAC9D,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAAW;QAC7B,2EAA2E;QAC3E,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC;CACF"}
+{"version":3,"file":"jsonl-knowledge-backend.js","sourceRoot":"","sources":["../../src/smart-agent/jsonl-knowledge-backend.ts"],"names":[],"mappings":"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"}

package/dist/smart-agent/pg-pool.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Real `pg.Pool` provider for the skill plugin-host's `postgres` catalog.
+ *
+ * The catalog store ({@link makePgCatalogStore} in `@mcp-abap-adt/llm-agent-libs`)
+ * speaks to the database through the minimal {@link IPgPool} seam
+ * (`query(sql, params?) → { rows, rowCount }`) so it carries NO `pg` dependency.
+ * That store does INSERT/SELECT/UPDATE on a single-row table but never CREATEs it,
+ * so production deployments need (a) a real connection and (b) the catalog table
+ * to exist. This module provides BOTH.
+ *
+ * `pg` is imported DYNAMICALLY (mirroring `@mcp-abap-adt/pg-vector-rag`) so it
+ * stays a soft dependency: the module imports with zero I/O, the Pool is created
+ * lazily on first `query()`, and unit tests inject a fake pool instead (the
+ * factory never touches a real DB).
+ *
+ * The DDL matches the columns {@link makePgCatalogStore} reads/writes exactly:
+ *   `id text PRIMARY KEY, revision text NOT NULL, snapshot jsonb NOT NULL`.
+ */
+import type { IPgPool } from '@mcp-abap-adt/llm-agent-libs';
+/** Minimal shape of the `pg.Pool` we consume (a subset of the real driver). */
+interface RawPgPool {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+        rowCount: number | null;
+    }>;
+    /** The real `pg.Pool` exposes this; closes all sockets in the pool. */
+    end(): Promise<void>;
+}
+/**
+ * Build an {@link IPgPool} backed by a real `pg.Pool`. The Pool is created on
+ * first use (lazy dynamic import) and the catalog table is ensured exactly once
+ * before the first query reaches the catalog store.
+ *
+ * @param connectionString libpq connection string.
+ * @param table catalog table name (defaults to `skills_catalog`, matching the
+ *   catalog store default; pass the SAME value configured on `catalog.table`).
+ */
+export declare function makePgPool(connectionString: string, table?: string, deps?: {
+    createPool?: (cs: string) => Promise<RawPgPool>;
+}): IPgPool & {
+    end(): Promise<void>;
+};
+/**
+ * Build a READ-ONLY {@link IPgPool} backed by a real `pg.Pool`. Identical lazy
+ * dynamic-`import('pg')` Pool construction as {@link makePgPool}, but it NEVER
+ * runs DDL (no `CREATE TABLE`). A recall-only process configured with READ-ONLY
+ * pg credentials uses THIS pool so it does not crash attempting to create the
+ * catalog table it only ever reads.
+ *
+ * @param connectionString libpq connection string.
+ */
+export declare function makePgReadPool(connectionString: string, deps?: {
+    createPool?: (cs: string) => Promise<RawPgPool>;
+}): IPgPool & {
+    end(): Promise<void>;
+};
+export {};
+//# sourceMappingURL=pg-pool.d.ts.map

package/dist/smart-agent/pg-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-pool.d.ts","sourceRoot":"","sources":["../../src/smart-agent/pg-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAqB5D,+EAA+E;AAC/E,UAAU,SAAS;IACjB,KAAK,CACH,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACzD,uEAAuE;IACvE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAaD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,gBAAgB,EAAE,MAAM,EACxB,KAAK,GAAE,MAAsB,EAC7B,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAA;CAAO,GAC7D,OAAO,GAAG;IAAE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAsDpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,gBAAgB,EAAE,MAAM,EACxB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAA;CAAO,GAC7D,OAAO,GAAG;IAAE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAiCpC"}

package/dist/smart-agent/pg-pool.js

@@ -0,0 +1,149 @@
+/**
+ * Real `pg.Pool` provider for the skill plugin-host's `postgres` catalog.
+ *
+ * The catalog store ({@link makePgCatalogStore} in `@mcp-abap-adt/llm-agent-libs`)
+ * speaks to the database through the minimal {@link IPgPool} seam
+ * (`query(sql, params?) → { rows, rowCount }`) so it carries NO `pg` dependency.
+ * That store does INSERT/SELECT/UPDATE on a single-row table but never CREATEs it,
+ * so production deployments need (a) a real connection and (b) the catalog table
+ * to exist. This module provides BOTH.
+ *
+ * `pg` is imported DYNAMICALLY (mirroring `@mcp-abap-adt/pg-vector-rag`) so it
+ * stays a soft dependency: the module imports with zero I/O, the Pool is created
+ * lazily on first `query()`, and unit tests inject a fake pool instead (the
+ * factory never touches a real DB).
+ *
+ * The DDL matches the columns {@link makePgCatalogStore} reads/writes exactly:
+ *   `id text PRIMARY KEY, revision text NOT NULL, snapshot jsonb NOT NULL`.
+ */
+/** Default catalog table — agrees with `makePgCatalogStore`'s default. */
+const DEFAULT_TABLE = 'skills_catalog';
+/**
+ * Strict SQL-identifier regex for the catalog table — bare identifier or one
+ * optional `schema.table` dot. The table name is interpolated into DDL/queries,
+ * so it MUST NOT trust its caller (belt-and-suspenders with the config-layer
+ * validation in `skill-plugins-config.ts`).
+ */
+const SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function assertSafeTable(table) {
+    if (!SQL_IDENTIFIER.test(table)) {
+        throw new Error(`pg-pool: invalid catalog table identifier '${table}' (must match ${SQL_IDENTIFIER.source})`);
+    }
+}
+/** Lazily resolve the `pg` driver and construct a real Pool. */
+async function createRawPool(connectionString) {
+    const mod = (await import('pg'));
+    const PoolCtor = mod.Pool ?? mod.default?.Pool;
+    if (!PoolCtor)
+        throw new Error('pg module did not expose Pool');
+    return new PoolCtor({ connectionString });
+}
+/**
+ * Build an {@link IPgPool} backed by a real `pg.Pool`. The Pool is created on
+ * first use (lazy dynamic import) and the catalog table is ensured exactly once
+ * before the first query reaches the catalog store.
+ *
+ * @param connectionString libpq connection string.
+ * @param table catalog table name (defaults to `skills_catalog`, matching the
+ *   catalog store default; pass the SAME value configured on `catalog.table`).
+ */
+export function makePgPool(connectionString, table = DEFAULT_TABLE, deps = {}) {
+    assertSafeTable(table);
+    const create = deps.createPool ?? createRawPool;
+    let poolPromise;
+    let ensured;
+    // The real `pg.Pool` throws on a second `.end()`. Overlapping cleanup paths
+    // (initSkillHost on failure + the start() finally + closeFns) may all reach
+    // here, so guard so a second end() is a no-op rather than a throw.
+    let ended = false;
+    const getPool = () => {
+        if (!poolPromise)
+            poolPromise = create(connectionString);
+        return poolPromise;
+    };
+    const ensureTable = (pool) => {
+        if (!ensured) {
+            ensured = pool
+                .query(`CREATE TABLE IF NOT EXISTS ${table} (` +
+                'id text PRIMARY KEY, ' +
+                'revision text NOT NULL, ' +
+                'snapshot jsonb NOT NULL)')
+                .then(() => undefined);
+        }
+        return ensured;
+    };
+    return {
+        async query(sql, params) {
+            // A query after end() is a programming error: getPool() would lazily build a
+            // BRAND-NEW pool that the (now no-op) end() can never close → socket leak.
+            // Fail loud instead of silently reopening an unclosable pool.
+            if (ended)
+                throw new Error('pg pool is closed (query after end())');
+            const pool = await getPool();
+            await ensureTable(pool);
+            const res = await pool.query(sql, params);
+            return { rows: res.rows, rowCount: res.rowCount ?? 0 };
+        },
+        // Close the real pool so its sockets do not outlive server shutdown.
+        // AWAIT `poolPromise` (not a `createdPool` snapshot): if creation is still
+        // IN FLIGHT when end() is called, we wait for it and close the resulting
+        // pool — otherwise a pool that finishes creating after end() would leak.
+        // Idempotent: a second end() is a no-op (the raw pg.Pool throws on double-end).
+        async end() {
+            if (ended)
+                return;
+            ended = true;
+            if (poolPromise) {
+                const pool = await poolPromise.catch(() => undefined);
+                if (pool)
+                    await pool.end();
+            }
+        },
+    };
+}
+/**
+ * Build a READ-ONLY {@link IPgPool} backed by a real `pg.Pool`. Identical lazy
+ * dynamic-`import('pg')` Pool construction as {@link makePgPool}, but it NEVER
+ * runs DDL (no `CREATE TABLE`). A recall-only process configured with READ-ONLY
+ * pg credentials uses THIS pool so it does not crash attempting to create the
+ * catalog table it only ever reads.
+ *
+ * @param connectionString libpq connection string.
+ */
+export function makePgReadPool(connectionString, deps = {}) {
+    const create = deps.createPool ?? createRawPool;
+    let poolPromise;
+    // The real `pg.Pool` throws on a second `.end()`; guard for idempotency.
+    let ended = false;
+    const getPool = () => {
+        if (!poolPromise)
+            poolPromise = create(connectionString);
+        return poolPromise;
+    };
+    return {
+        async query(sql, params) {
+            // A query after end() is a programming error: getPool() would lazily build a
+            // BRAND-NEW pool that the (now no-op) end() can never close → socket leak.
+            // Fail loud instead of silently reopening an unclosable pool.
+            if (ended)
+                throw new Error('pg pool is closed (query after end())');
+            const pool = await getPool();
+            const res = await pool.query(sql, params);
+            return { rows: res.rows, rowCount: res.rowCount ?? 0 };
+        },
+        // Close the pool, awaiting an IN-FLIGHT creation (see makePgPool.end). A pool
+        // that finishes creating after end() must still be closed, not leaked.
+        // Idempotent: a second end() is a no-op (the raw pg.Pool throws on double-end).
+        async end() {
+            if (ended)
+                return;
+            ended = true;
+            if (poolPromise) {
+                const pool = await poolPromise.catch(() => undefined);
+                if (pool)
+                    await pool.end();
+            }
+        },
+    };
+}
+//# sourceMappingURL=pg-pool.js.map

package/dist/smart-agent/pg-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-pool.js","sourceRoot":"","sources":["../../src/smart-agent/pg-pool.ts"],"names":[],"mappings":"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"}

package/dist/smart-agent/skill-plugins-config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Parse + validate the top-level `skillPlugins:` server config key into a
+ * normalized {@link SkillPluginsConfig}.
+ *
+ * This is the skill PLUGIN-HOST config — a NEW key, DISTINCT from the existing
+ * `skills:` ({@link SmartServerSkillsConfig}, the FS skill-MANAGER consumed by
+ * `resolveSkillManager`). The two are unrelated features and must not collide.
+ *
+ * The host materialises consumer-supplied domain skills into a grouped
+ * skills-RAG and the pipelines recall from it. This module only normalizes +
+ * fail-loud validates the deployment config; assembly lives in the host factory.
+ */
+/** Normalized store selection. A persistent (`qdrant`) store carries its URL/auth. */
+export type SkillPluginsStoreConfig = {
+    type: 'in-memory';
+} | {
+    type: 'qdrant';
+    url: string;
+    apiKey?: string;
+    collection?: string;
+};
+/** Normalized catalog selection. A persistent store requires a `postgres` catalog. */
+export type SkillPluginsCatalogConfig = {
+    type: 'in-process';
+} | {
+    type: 'postgres';
+    connectionString: string;
+    table?: string;
+};
+/** A FETCHED source: a marketplace/registry pulled into memory. Requires a
+ *  non-empty `enabled` plugin list (omitting it is a config error, NOT "load all"). */
+export interface SkillPluginsFetchedSource {
+    id: string;
+    registry?: string;
+    enabled?: readonly string[];
+    /** Acquisition/materialisation strategy name (validated via the registry). */
+    strategy?: string;
+    /** Opaque, strategy-specific config (incl. any placement rules). */
+    strategyConfig?: Record<string, unknown>;
+}
+/** A PROGRAMMATIC source: the consumer's pre-filtered, in-memory record set.
+ *  Carries NO `enabled` (it is already the exact set); each record carries a `group`. */
+export interface SkillPluginsRecordsSource {
+    id: string;
+    records: readonly unknown[];
+}
+export type SkillPluginsSource = SkillPluginsFetchedSource | SkillPluginsRecordsSource;
+/** The normalized skill plugin-host config (defaults applied). */
+export interface SkillPluginsConfig {
+    /** Consumption mode. Only `implicit` is accepted this phase. */
+    mode: 'implicit';
+    store: SkillPluginsStoreConfig;
+    /** Stable vector-space id; MANDATORY for a persistent (qdrant) store. */
+    embeddingSpaceId?: string;
+    /** Serving embedder selection (provider + optional model). */
+    embedder?: {
+        provider: string;
+        model?: string;
+    };
+    /** Declared embedding dimension (skips the probe embed when set). */
+    dimension?: number;
+    catalog: SkillPluginsCatalogConfig;
+    /** Max records recalled per query. Default 4. */
+    k: number;
+    /** Min cosine similarity in [0,1]; below → dropped. Default 0.3. */
+    threshold: number;
+    /** Self-assembling pipelines' "Relevant skills" block char budget. Default 4000. */
+    maxInjectChars: number;
+    /** Chunking bound. Default 1500. */
+    chunk: {
+        maxChars: number;
+    };
+    /** true → a source failure aborts that group; false → carry-forward. Default false. */
+    strict: boolean;
+    /** publishCatalog CAS retries on a concurrent-loader conflict. Default 3. */
+    catalogCasMaxAttempts: number;
+    /** Retired-generation grace before background reclaim (ms). Default 30000 (>= 1000). */
+    retiredGraceMs: number;
+    /** Orphan-generation grace before crash-resumable reclaim (ms). Default 3600000. */
+    orphanGraceMs: number;
+    /** Recall deadline (ms) — defaults to floor(retiredGraceMs*0.8) for qdrant; unused in-memory. */
+    recallTimeoutMs?: number;
+    /** Single collection the controller planner recalls (self-assembling pipelines). */
+    controllerSkillGroup?: string;
+    /** Which collections assembler pipelines read (implicit). Omit → all produced. */
+    serveCollections?: readonly string[];
+    /** false = recall-only (no ingest); requires a persistent store. Default true. */
+    loadOnStartup: boolean;
+    /** Acquisition sources. Absent → recall-only (a persistent store must be present). */
+    sources?: readonly SkillPluginsSource[];
+}
+/**
+ * Parse + validate the raw `skillPlugins:` YAML/object into a normalized
+ * {@link SkillPluginsConfig}. Throws a fail-loud `Error` on any invalid config.
+ */
+export declare function parseSkillPluginsConfig(raw: unknown): SkillPluginsConfig;
+//# sourceMappingURL=skill-plugins-config.d.ts.map

package/dist/smart-agent/skill-plugins-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-plugins-config.d.ts","sourceRoot":"","sources":["../../src/smart-agent/skill-plugins-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,sFAAsF;AACtF,MAAM,MAAM,uBAAuB,GAC/B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,sFAAsF;AACtF,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;uFACuF;AACvF,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;yFACyF;AACzF,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B;AAED,MAAM,MAAM,kBAAkB,GAC1B,yBAAyB,GACzB,yBAAyB,CAAC;AAE9B,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,uBAAuB,CAAC;IAC/B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,yBAAyB,CAAC;IACnC,iDAAiD;IACjD,CAAC,EAAE,MAAM,CAAC;IACV,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,uFAAuF;IACvF,MAAM,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,cAAc,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kFAAkF;IAClF,aAAa,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC;AA0ID;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CA+NxE"}