@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/ingest/_services/fam-scan.control-service.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Scan_ControlService = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const config_catalog_const_1 = require("../../../_collections/config-catalog.const");
+const config_control_service_1 = require("../../../_routes/server/config/config.control-service");
+const fam_file_routing_util_1 = require("../_collections/fam-file-routing.util");
+const fam_glob_match_util_1 = require("../_collections/fam-glob-match.util");
+const fam_scan_path_util_1 = require("../_collections/fam-scan-path.util");
+const fam_secret_exclude_util_1 = require("../_collections/fam-secret-exclude.util");
+/**
+ * `FAM_Scan_ControlService` (SP-4.1, dsgn-004 §1/§2/§6) — a `write(scan-*)` fájl-felderítő + routing
+ * + biztonsági belépési pontja. A `scan.path` (file/folder/project) biztonságos bejárása
+ * (path-traversal guard + ignore-patterns + secret-exclude + méret-plafon), majd minden felderített
+ * fájl `documents` / `codebase` / `skip` route-olása (dsgn-004 §2), MIELŐTT a chunkerek (SP-4.2)
+ * futnának. Az orchestrátor (`FAM_Ingest_ControlService`) ezt hívja a scope-resolve UTÁN.
+ *
+ * Singleton (a felderítés állapot-mentes; a config-resolve a `FAM_Config_ControlService`-en).
+ *
+ * **BOUNDARY:** ez NEM hívja a chunkert/embeddinget — csak felderít + route-ol. A `scopePath` itt
+ * MÁR canonical (a MP-3 `resolveForWrite` feloldotta az orchestrátorban). A scope-resolve hibája a
+ * scan ELŐTT bukik (a run `failed`), ezért ide már csak feloldott scope érkezik.
+ */
+class FAM_Scan_ControlService {
+    static _instance;
+    /** Default issuer a scan-műveletekhez. */
+    issuer = 'FAM_Scan_ControlService';
+    static getInstance() {
+        if (!FAM_Scan_ControlService._instance) {
+            FAM_Scan_ControlService._instance = new FAM_Scan_ControlService();
+        }
+        return FAM_Scan_ControlService._instance;
+    }
+    /**
+     * Egy scan-művelet fájl-felderítése + routingja (dsgn-004 §1/§2/§6). A `scan-file` egyetlen
+     * fájl; a `scan-folder`/`scan-project` rekurzív bejárás (a könyvtárakat az ignore-patterns
+     * bejárás KÖZBEN kihagyja — ne lépjen `node_modules`-ba). A secret-exclude a routing ELŐTT fut;
+     * a méret-plafon feletti / olvashatatlan / skip-routed fájlok a `skippedFiles`-be (audit, nem néma).
+     */
+    async discover(set) {
+        const resolvedRoot = fam_scan_path_util_1.FAM_ScanPath_Util.resolveRoot(set.path, this.issuer);
+        const ignorePatterns = await this.resolveIgnorePatterns(set.scopePath, set.exclude);
+        const maxFileSizeBytes = await this.resolveMaxFileSize(set.scopePath);
+        const followSymlinks = await this.resolveFollowSymlinks(set.scopePath);
+        const routedFiles = [];
+        const skippedFiles = [];
+        // A felderített abszolút fájlok (file = 1 db; folder/project = rekurzív bejárás).
+        const absoluteFiles = set.operation === 'scan-file'
+            ? [resolvedRoot]
+            : this.walkDirectory(resolvedRoot, resolvedRoot, ignorePatterns, followSymlinks);
+        for (const absolutePath of absoluteFiles) {
+            const relativePath = set.operation === 'scan-file'
+                ? path.basename(resolvedRoot)
+                : fam_scan_path_util_1.FAM_ScanPath_Util.toRelative(resolvedRoot, absolutePath);
+            const routed = this.classifyFile({
+                absolutePath: absolutePath,
+                relativePath: relativePath,
+                ignorePatterns: ignorePatterns,
+                includePatterns: set.include,
+                maxFileSizeBytes: maxFileSizeBytes,
+                tableOverride: set.tableOverride,
+            });
+            if (routed.route === 'skip') {
+                skippedFiles.push(routed);
+            }
+            else {
+                routedFiles.push(routed);
+            }
+        }
+        return {
+            resolvedRoot: resolvedRoot,
+            routedFiles: routedFiles,
+            skippedFiles: skippedFiles,
+            tables: this.collectTables(routedFiles),
+        };
+    }
+    /**
+     * Egy fájl osztályozása (dsgn-004 §2/§6): a secret-exclude + ignore-patterns + include-szűrés +
+     * méret-plafon, majd a file-típus-routing (vagy `tableOverride`). A skip-okot a `skipReason`
+     * hordozza (audit). A vizsgálati sorrend: secret → ignore → include → size → route.
+     */
+    classifyFile(set) {
+        const base = {
+            absolutePath: set.absolutePath,
+            relativePath: set.relativePath,
+        };
+        // (1) Secret-exclude (a routing ELŐTT, dsgn-004 §6.3) — SOHA nem ingestálódik.
+        if (fam_secret_exclude_util_1.FAM_SecretExclude_Util.isSecret(set.relativePath)) {
+            return { ...base, route: 'skip', skipReason: 'secret-exclude (filename/path-based; content-PII scan = BACKLOG)' };
+        }
+        // (2) Ignore-patterns (dsgn-004 §6.2) — node_modules/.git/build/dist/lock/... + a config + input-exclude.
+        if (fam_glob_match_util_1.FAM_GlobMatch_Util.matchesAny(set.relativePath, set.ignorePatterns)) {
+            return { ...base, route: 'skip', skipReason: 'ignore-pattern' };
+        }
+        // (3) Include-szűrés (ha megadva: csak az illeszkedő fájl megy tovább, dsgn-003 §3.1).
+        if (set.includePatterns && set.includePatterns.length && !fam_glob_match_util_1.FAM_GlobMatch_Util.matchesAny(set.relativePath, set.includePatterns)) {
+            return { ...base, route: 'skip', skipReason: 'include-filter' };
+        }
+        // (4) Méret-plafon (dsgn-004 §6.4) — az óriás-fájl ne fújja fel a memóriát/költséget.
+        const sizeBytes = this.fileSizeSafe(set.absolutePath);
+        if (sizeBytes > set.maxFileSizeBytes) {
+            return { ...base, route: 'skip', skipReason: `file too large (${sizeBytes} > ${set.maxFileSizeBytes} bytes)` };
+        }
+        // (5) File-típus-routing (vagy explicit tableOverride, dsgn-004 §2).
+        const route = set.tableOverride ?? fam_file_routing_util_1.FAM_FileRouting_Util.route(set.relativePath);
+        if (route === 'skip') {
+            return { ...base, route: 'skip', skipReason: 'unrouted file-type' };
+        }
+        return { ...base, route: route };
+    }
+    /**
+     * Rekurzív könyvtár-bejárás (a `scan-folder`/`scan-project` felderítője). Az ignore-patterns a
+     * KÖNYVTÁRAKAT bejárás KÖZBEN kihagyja (ne lépjen `node_modules`-ba — teljesítmény + biztonság).
+     * A symlinkeket alapból NEM követi (`followSymlinks` config); a path-traversal guardot minden
+     * fájlra futtatja (a feloldott valódi útvonal a gyökér alatt kell maradjon).
+     */
+    walkDirectory(currentDir, resolvedRoot, ignorePatterns, followSymlinks) {
+        const result = [];
+        let entries;
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            // Olvashatatlan könyvtár → kihagyjuk (a per-fájl olvasás-hiba a chunk-fázisban kezelt).
+            return result;
+        }
+        for (const entry of entries) {
+            const entryPath = path.join(currentDir, entry.name);
+            const relativePath = fam_scan_path_util_1.FAM_ScanPath_Util.toRelative(resolvedRoot, entryPath);
+            // Symlink-kezelés: alapból NEM követjük (path-traversal védelem, dsgn-004 §6.1).
+            if (entry.isSymbolicLink() && !followSymlinks) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                // Az ignore-patterns a könyvtárat bejárás közben kihagyja (ne lépjen be).
+                if (fam_glob_match_util_1.FAM_GlobMatch_Util.matchesAny(relativePath, ignorePatterns)
+                    || fam_glob_match_util_1.FAM_GlobMatch_Util.matchesAny(relativePath + '/', ignorePatterns)) {
+                    continue;
+                }
+                // Path-traversal guard (a feloldott valódi útvonal a gyökér alatt kell maradjon).
+                if (!this.isInsideRootSafe(resolvedRoot, entryPath)) {
+                    continue;
+                }
+                result.push(...this.walkDirectory(entryPath, resolvedRoot, ignorePatterns, followSymlinks));
+                continue;
+            }
+            if (entry.isFile()) {
+                if (this.isInsideRootSafe(resolvedRoot, entryPath)) {
+                    result.push(entryPath);
+                }
+            }
+        }
+        return result;
+    }
+    /** Path-traversal guard egy bejárt útvonalra (a guard-hiba itt csendes-skip, nem run-bukás). */
+    isInsideRootSafe(resolvedRoot, candidatePath) {
+        try {
+            const real = fs.realpathSync(candidatePath);
+            return fam_scan_path_util_1.FAM_ScanPath_Util.isInside(resolvedRoot, real);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Egy fájl mérete byte-ban (olvashatatlan → `Number.MAX_SAFE_INTEGER`, hogy a méret-plafon kiszűrje). */
+    fileSizeSafe(absolutePath) {
+        try {
+            return fs.statSync(absolutePath).size;
+        }
+        catch {
+            return Number.MAX_SAFE_INTEGER;
+        }
+    }
+    /**
+     * A route-olt fájlok érintett tárai (a nem-`skip` route-ok uniója; scan-project többet is
+     * érinthet). Automata routingnál `documents`/`codebase`; `tableOverride`-nál bármely fő tár.
+     */
+    collectTables(routedFiles) {
+        const tables = new Set();
+        for (const file of routedFiles) {
+            if (file.route !== 'skip') {
+                tables.add(file.route);
+            }
+        }
+        return Array.from(tables);
+    }
+    /**
+     * Az effektív ignore-patterns: a config `scan.ignorePatterns` (default `SCAN_IGNORE_PATTERNS_DEFAULT`)
+     * + az input `exclude` HOZZÁADVA (dsgn-004 §6.2 — a `write.scan.exclude` HOZZÁADÓDIK, NEM felülír).
+     */
+    async resolveIgnorePatterns(scopePath, exclude) {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('scan.ignorePatterns', { scopePath: scopePath });
+        const configPatterns = Array.isArray(resolved.value)
+            ? resolved.value.filter((item) => typeof item === 'string')
+            : config_catalog_const_1.SCAN_IGNORE_PATTERNS_DEFAULT;
+        return [...configPatterns, ...(exclude ?? [])];
+    }
+    /** A méret-plafon a config-ból (`scan.maxFileSizeBytes`, default 1 MB). */
+    async resolveMaxFileSize(scopePath) {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('scan.maxFileSizeBytes', { scopePath: scopePath });
+        return typeof resolved.value === 'number' ? resolved.value : 1048576;
+    }
+    /** A symlink-követés a config-ból (`scan.followSymlinks`, default false — path-traversal védelem). */
+    async resolveFollowSymlinks(scopePath) {
+        const resolved = await config_control_service_1.FAM_Config_ControlService.getInstance().resolve('scan.followSymlinks', { scopePath: scopePath });
+        return typeof resolved.value === 'boolean' ? resolved.value : false;
+    }
+}
+exports.FAM_Scan_ControlService = FAM_Scan_ControlService;

package/build/src/_modules/ingest/index.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * `ingest` modul barrel (MP-4, dsgn-004) — a scan → chunk → delta → embed → persist ingest-engine
+ * publikus felülete. A fogyasztó-MP-k (MP-6 `write` MCP-eszköz / REST a `scanFile`/`scanFolder`/
+ * `scanProject`-hez + `list_scan_runs`/delete-run capability) innen importálnak.
+ *
+ * Boundary (dsgn-004 BOUNDARY): MP-4 az ingest-ENGINE — a scan-t TRIGGERELŐ MCP-tool / REST = MP-6;
+ * a retrieval = MP-5. A markdown-chunker NEM a Dynamo `DyNTS_DAI_DocChunking_Util`-t használja
+ * (az ClickUp-domain-kötött, nem plain string-API), hanem a CCAP header-aware algoritmus
+ * projekt-lokális portját (BFR-AM-005 mintára). PDF + dataflow/runflow code-intelligence + aktív
+ * file-watch = BACKLOG (dsgn-004 §2/§3 megjegyzés). A tartalmi PII/secret-detektálás = BACKLOG
+ * (MVP1 csak fájlnév-/útvonal-alapú secret-exclude).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_IngestRun_DataService = exports.FAM_ContentHash_Util = exports.FAM_DeltaCompare_Util = exports.FAM_SlidingChunker_Util = exports.FAM_MdChunker_Util = exports.FAM_TsChunker_Util = exports.FAM_Chunker_ControlService = exports.FAM_GlobMatch_Util = exports.FAM_SecretExclude_Util = exports.FAM_ScanPath_Util = exports.FAM_FileRouting_Util = exports.FAM_Scan_ControlService = exports.FAM_Ingest_ControlService = void 0;
+// SP-4.4 — ingest-orchestrátor (a `write(scan-*)` belépési pontja + group-by-run/delete-run)
+var fam_ingest_control_service_1 = require("./_services/fam-ingest.control-service");
+Object.defineProperty(exports, "FAM_Ingest_ControlService", { enumerable: true, get: function () { return fam_ingest_control_service_1.FAM_Ingest_ControlService; } });
+// SP-4.1 — scan + felderítés + routing + security
+var fam_scan_control_service_1 = require("./_services/fam-scan.control-service");
+Object.defineProperty(exports, "FAM_Scan_ControlService", { enumerable: true, get: function () { return fam_scan_control_service_1.FAM_Scan_ControlService; } });
+var fam_file_routing_util_1 = require("./_collections/fam-file-routing.util");
+Object.defineProperty(exports, "FAM_FileRouting_Util", { enumerable: true, get: function () { return fam_file_routing_util_1.FAM_FileRouting_Util; } });
+var fam_scan_path_util_1 = require("./_collections/fam-scan-path.util");
+Object.defineProperty(exports, "FAM_ScanPath_Util", { enumerable: true, get: function () { return fam_scan_path_util_1.FAM_ScanPath_Util; } });
+var fam_secret_exclude_util_1 = require("./_collections/fam-secret-exclude.util");
+Object.defineProperty(exports, "FAM_SecretExclude_Util", { enumerable: true, get: function () { return fam_secret_exclude_util_1.FAM_SecretExclude_Util; } });
+var fam_glob_match_util_1 = require("./_collections/fam-glob-match.util");
+Object.defineProperty(exports, "FAM_GlobMatch_Util", { enumerable: true, get: function () { return fam_glob_match_util_1.FAM_GlobMatch_Util; } });
+// SP-4.2 — chunkerek (dispatch + project-local utils)
+var fam_chunker_control_service_1 = require("./_services/fam-chunker.control-service");
+Object.defineProperty(exports, "FAM_Chunker_ControlService", { enumerable: true, get: function () { return fam_chunker_control_service_1.FAM_Chunker_ControlService; } });
+var fam_ts_chunker_util_1 = require("./_collections/fam-ts-chunker.util");
+Object.defineProperty(exports, "FAM_TsChunker_Util", { enumerable: true, get: function () { return fam_ts_chunker_util_1.FAM_TsChunker_Util; } });
+var fam_md_chunker_util_1 = require("./_collections/fam-md-chunker.util");
+Object.defineProperty(exports, "FAM_MdChunker_Util", { enumerable: true, get: function () { return fam_md_chunker_util_1.FAM_MdChunker_Util; } });
+var fam_sliding_chunker_util_1 = require("./_collections/fam-sliding-chunker.util");
+Object.defineProperty(exports, "FAM_SlidingChunker_Util", { enumerable: true, get: function () { return fam_sliding_chunker_util_1.FAM_SlidingChunker_Util; } });
+// SP-4.3 — idempotens delta-detection
+var fam_delta_compare_util_1 = require("./_services/fam-delta-compare.util");
+Object.defineProperty(exports, "FAM_DeltaCompare_Util", { enumerable: true, get: function () { return fam_delta_compare_util_1.FAM_DeltaCompare_Util; } });
+var fam_content_hash_util_1 = require("./_collections/fam-content-hash.util");
+Object.defineProperty(exports, "FAM_ContentHash_Util", { enumerable: true, get: function () { return fam_content_hash_util_1.FAM_ContentHash_Util; } });
+// SP-4.4 — ingest-run tracking
+var fam_ingest_run_data_service_1 = require("./_services/fam-ingest-run.data-service");
+Object.defineProperty(exports, "FAM_IngestRun_DataService", { enumerable: true, get: function () { return fam_ingest_run_data_service_1.FAM_IngestRun_DataService; } });

package/build/src/_modules/mcp/_collections/fam-core-tools.const.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_CORE_TOOLS = void 0;
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const fam_read_tool_service_1 = require("../_services/fam-read-tool.service");
+const fam_write_tool_service_1 = require("../_services/fam-write-tool.service");
+const fam_capabilities_tool_service_1 = require("../_services/fam-capabilities-tool.service");
+/**
+ * A 3 ADVERTISED MCP core-tool definíciója (SP-6.1/6.2/6.3/6.4, dsgn-003 §2/§3/§4/§5). EZ a
+ * single-source a `read`/`write`/`capabilities` hirdetett tool-listához — a stdio `tools/list` PONTOSAN
+ * ezt a 3-at adja vissza (dsgn-003 §6.1), a speciális eszközök NEM kerülnek ide (csak a
+ * `FAM_CapabilityRegistry`-ben élnek — diszjunkció, dsgn-003 §6.6).
+ *
+ * Minden tool: agent-barát `description` (mely tár milyen tudást tárol, dsgn-003 §5) + JSON-schema
+ * input + handler (a transport-agnosztikus core-service-re delegál; a REST UGYANEZT hívja).
+ */
+/** A 6 fő RAG-tár leírása az LLM tár-választásához (dsgn-003 §5). */
+const TABLE_GUIDE = 'Tárak: `rules` (kódolási/architektúra/viselkedési szabályok), `documents` (specifikációk, dev-jegyzetek, '
+    + 'dokumentáció), `codebase` (forráskód-chunkok, szimbólumok), `knowledge` (tények, fogalmak, '
+    + 'döntés-indoklás), `coding_patterns` (minták, anti-minták, receptek), `memory` (session-/fejlesztés-/'
+    + 'incidens-történet, lessons-learned, user-preferenciák). A `reference` helper (alias/fogalom-feloldás) '
+    + 'NEM kereshető/írható közvetlenül.';
+/** A `read` query `tables` enum-értékei a fő tárak (a `reference` nem szerepel — helper). */
+const MAIN_TABLE_ENUM = Object.values(fam_table_type_enum_1.FAM_Table).filter((table) => table !== fam_table_type_enum_1.FAM_Table.reference);
+/** A nyers scope-lánc array-schema (`{ layer, rawName }[]`). */
+const SCOPE_LAYER_ARRAY = {
+    type: 'array',
+    description: 'Nyers scope-lánc (root→leaf): [{ layer, rawName }] párok (pl. organization=FutDevPro, project=Adventor).',
+    items: {
+        type: 'object',
+        properties: {
+            layer: { type: 'string', description: 'A dinamikus layer-név (pl. organization/project/module).' },
+            rawName: { type: 'string', description: 'A nyers (feloldatlan) scope-név (typo/STT/fonetikus is).' },
+        },
+        required: ['layer', 'rawName'],
+        additionalProperties: false,
+    },
+};
+/** A `read` tool input JSON-schema-ja (dsgn-003 §2.1). */
+const READ_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        queries: {
+            type: 'array',
+            description: 'Egy hívásban több, különböző táras + különböző kifejezésű query.',
+            items: {
+                type: 'object',
+                properties: {
+                    tables: {
+                        type: 'array',
+                        description: '1+ fő tár (a `reference` TILOS — helper).',
+                        items: { type: 'string', enum: MAIN_TABLE_ENUM },
+                    },
+                    query: { type: 'string', description: 'A keresési phrase.' },
+                    topK: { type: 'number', description: 'Találat-limit query-nként (config-default 5).' },
+                    minScore: { type: 'number', description: 'Minimum similarity-score küszöb.' },
+                    scopeFilter: SCOPE_LAYER_ARRAY,
+                    tagFilter: { type: 'array', items: { type: 'string' }, description: 'Tag-szűrő (OR).' },
+                    kindFilter: { type: 'string', description: 'Egyetlen kind-szűrő.' },
+                },
+                required: ['tables', 'query'],
+                additionalProperties: false,
+            },
+        },
+        includeContent: {
+            type: 'boolean', default: true,
+            description: 'Default true: a hit-ek `content`-tel térnek vissza (single-pass). false → kompakt lista.',
+        },
+        globalScopeFilter: SCOPE_LAYER_ARRAY,
+    },
+    required: ['queries'],
+    additionalProperties: false,
+};
+/** A `write` tool input JSON-schema-ja (dsgn-003 §3.1). */
+const WRITE_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        table: {
+            type: 'string', enum: Object.values(fam_table_type_enum_1.FAM_Table),
+            description: 'PONTOSAN egy fő tár (vagy `reference` a helper-CRUD-hoz).',
+        },
+        operation: {
+            type: 'string',
+            enum: ['create', 'update', 'delete', 'scan-file', 'scan-folder', 'scan-project', 're-embed', 'import'],
+            description: 'A művelet (create/update/delete/scan-*/re-embed/import).',
+        },
+        scopePath: SCOPE_LAYER_ARRAY,
+        kind: { type: 'string', description: 'Opcionális kind (per-tár default).' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Opcionális tagek.' },
+        content: { type: 'string', description: 'create/update tartalom (a vektorizálandó szöveg).' },
+        fields: { type: 'object', description: 'Per-tár specifikus mezők (dsgn-001 §4).', additionalProperties: true },
+        weight: { type: 'number', description: 'Opcionális retrieval-súly (default 1; coding_patterns 5).' },
+        importance: { type: 'number', description: 'Opcionális kvalitatív hangsúly (0..1).' },
+        target: {
+            type: 'object',
+            description: 'update/delete cél-azonosítás.',
+            properties: {
+                by: { type: 'string', enum: ['id', 'sourceFilePath', 'query'] },
+                value: { type: 'string' },
+            },
+            required: ['by', 'value'],
+            additionalProperties: false,
+        },
+        scan: {
+            type: 'object',
+            description: 'scan-* opciók (a scan-gyökér + glob-szűrők + dryRun).',
+            properties: {
+                path: { type: 'string', description: 'A scan-gyökér (file/folder/project).' },
+                include: { type: 'array', items: { type: 'string' } },
+                exclude: { type: 'array', items: { type: 'string' } },
+                dryRun: { type: 'boolean', description: 'Csak felderítés (NINCS embed+persist).' },
+            },
+            required: ['path'],
+            additionalProperties: false,
+        },
+        import: {
+            type: 'object',
+            description: 'import opciók (claude-mem migráció; a MP-11 engine thin-wrapper-én át — dsgn-009).',
+            properties: {
+                source: { type: 'string', description: 'Az import-forrás (claude-mem).' },
+                from: { type: 'string', enum: ['sqlite', 'export-json', 'worker-api'] },
+                path: { type: 'string' },
+            },
+            required: ['source'],
+            additionalProperties: false,
+        },
+    },
+    required: ['table', 'operation'],
+    additionalProperties: false,
+};
+/** A `capabilities` tool input JSON-schema-ja (dsgn-003 §4.1). */
+const CAPABILITIES_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        action: {
+            type: 'string', enum: ['list', 'describe', 'invoke'],
+            description: 'list (katalógus) / describe(name) (schema) / invoke(name, arguments) (futtatás).',
+        },
+        category: { type: 'string', description: 'Opcionális kategória-szűrés (`list`).' },
+        name: { type: 'string', description: 'A cél-eszköz neve (`describe`/`invoke` kötelező).' },
+        arguments: { type: 'object', description: 'Az `invoke` argumentumai.', additionalProperties: true },
+    },
+    required: ['action'],
+    additionalProperties: false,
+};
+/**
+ * A 3 advertised core-tool. A handler-ek a transport-agnosztikus core-service-ekre delegálnak — a
+ * REST-réteg (SP-6.5) UGYANEZEKET a service-eket hívja (paritás-garancia). A `read`/`capabilities`
+ * handler a `data`-t adja vissza; a `write` szintén (a strukturált output a `data`).
+ */
+exports.FAM_CORE_TOOLS = [
+    {
+        name: 'read',
+        description: 'Tudás keresése / lekérése / context-fetch — egylépcsős, MINDIG tartalommal. Egy hívásban '
+            + 'több tár + több query. ' + TABLE_GUIDE + ' A válasz dense-jelzést is ad (denseResults/totalRelevant/'
+            + 'truncated + javasolt szűrők), ha a találat túl sűrű.',
+        inputSchema: READ_INPUT_SCHEMA,
+        handler: async (args) => {
+            const data = await fam_read_tool_service_1.FAM_ReadTool_Service.getInstance().handle(args);
+            return { data: data };
+        },
+    },
+    {
+        name: 'write',
+        description: 'Tudás mentése / módosítása / törlése / scan / re-embed / import — explicit, PONTOSAN 1 tár. '
+            + 'A scope KÖTELEZŐ minden tartalom-műveletnél (create/scan-*/import). ' + TABLE_GUIDE
+            + ' A `delete` soft-delete; a scan automatikusan chunkol + embeddel (idempotens delta).',
+        inputSchema: WRITE_INPUT_SCHEMA,
+        handler: async (args) => {
+            const data = await fam_write_tool_service_1.FAM_WriteTool_Service.getInstance().handle(args);
+            return { data: data };
+        },
+    },
+    {
+        name: 'capabilities',
+        description: 'A ritkán használt speciális eszközök (config/diagnosztika, statisztika, inspekció, '
+            + 'karbantartás, import-migráció, debug) felderítése + meghívása EGYETLEN tool-on át. '
+            + 'action=list (katalógus) | describe (egy eszköz schema-ja) | invoke (egy eszköz futtatása). '
+            + 'Így az agent context tiszta marad (csak 3 advertised tool).',
+        inputSchema: CAPABILITIES_INPUT_SCHEMA,
+        handler: async (args) => {
+            const data = await fam_capabilities_tool_service_1.FAM_CapabilitiesTool_Service.getInstance().handle(args);
+            return { data: data };
+        },
+    },
+];

package/build/src/_modules/mcp/_models/interfaces/fam-mcp.interface.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_WriteOperation = exports.FAM_CapabilityCategory = void 0;
+/**
+ * A speciális (capability-only) eszköz-kategóriák (dsgn-003 §4.2). A `list` action ezekre csoportosít.
+ * Enum-konvenció (workspace base): key camelCase, value kebab-case.
+ */
+var FAM_CapabilityCategory;
+(function (FAM_CapabilityCategory) {
+    FAM_CapabilityCategory["configDiagnostics"] = "config-diagnostics";
+    FAM_CapabilityCategory["highLevelStats"] = "high-level-stats";
+    FAM_CapabilityCategory["inspection"] = "inspection";
+    FAM_CapabilityCategory["maintenance"] = "maintenance";
+    FAM_CapabilityCategory["importMigration"] = "import-migration";
+    FAM_CapabilityCategory["debug"] = "debug";
+})(FAM_CapabilityCategory || (exports.FAM_CapabilityCategory = FAM_CapabilityCategory = {}));
+/**
+ * A `write` művelet-fajtái (dsgn-003 §3.1 operation enum). Enum-konvenció: key camelCase, value
+ * kebab-case (a wire-érték a dsgn-003 string-je).
+ */
+var FAM_WriteOperation;
+(function (FAM_WriteOperation) {
+    FAM_WriteOperation["create"] = "create";
+    FAM_WriteOperation["update"] = "update";
+    FAM_WriteOperation["delete"] = "delete";
+    FAM_WriteOperation["scanFile"] = "scan-file";
+    FAM_WriteOperation["scanFolder"] = "scan-folder";
+    FAM_WriteOperation["scanProject"] = "scan-project";
+    FAM_WriteOperation["reEmbed"] = "re-embed";
+    FAM_WriteOperation["import"] = "import";
+})(FAM_WriteOperation || (exports.FAM_WriteOperation = FAM_WriteOperation = {}));

package/build/src/_modules/mcp/_services/fam-capabilities-tool.service.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_CapabilitiesTool_Service = void 0;
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const fam_capability_registry_service_1 = require("./fam-capability-registry.service");
+/**
+ * `FAM_CapabilitiesTool_Service` (SP-6.4, dsgn-003 §4) — a `capabilities` core-tool handler-je.
+ * Singleton. EGY belépési pont (`handle`), amit MIND az MCP-tool, MIND a REST `POST /capabilities` hív.
+ *
+ * Három action (dsgn-003 §4.1):
+ *   - `list` → kategóriák + tool-nevek + egysoros leírás (a `FAM_CapabilityRegistry`-ből, single-source),
+ *   - `describe(name)` → a tool teljes input-schema-ja + kategória + leírás,
+ *   - `invoke(name, arguments)` → a capability handler futtatása + eredmény (vagy strukturált hiba).
+ *
+ * **Diszjunkció (dsgn-003 §6.6):** ez az EGYETLEN út a speciális eszközökhöz — azok SOHA nem
+ * advertised tool-ok. Ismeretlen `name` → `FAM-MCP-DISPATCH-002`; late-bind capability `invoke`-ja →
+ * clear "pending MP-X" hiba (a registry handler-éből). Néma hiba TILOS.
+ */
+class FAM_CapabilitiesTool_Service {
+    static _instance;
+    /** Default issuer (a dispatch-hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_CapabilitiesTool_Service';
+    static getInstance() {
+        if (!FAM_CapabilitiesTool_Service._instance) {
+            FAM_CapabilitiesTool_Service._instance = new FAM_CapabilitiesTool_Service();
+        }
+        return FAM_CapabilitiesTool_Service._instance;
+    }
+    /**
+     * A `capabilities` core-handler (dsgn-003 §4.1). A `action` választ a list/describe/invoke között;
+     * a `describe`/`invoke` `name`-et igényel. Az `invoke` a registry handler-ét futtatja (a dobott
+     * `DyFM_Error`-t az adaptor/REST egységesen strukturált hibává fordítja).
+     */
+    async handle(input) {
+        const action = input?.action;
+        switch (action) {
+            case 'list':
+                return this.handleList(input.category);
+            case 'describe':
+                return this.handleDescribe(input.name);
+            case 'invoke':
+                return this.handleInvoke(input.name, input.arguments);
+            default:
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpSchemaMismatch,
+                    message: `Ismeretlen \`capabilities\` action: '${action}'. Megengedett: list | describe | invoke.`,
+                    issuer: this.issuer,
+                    context: { operation: 'capabilities-dispatch' },
+                });
+        }
+    }
+    /** `list` → kategória → tool-nevek + egysoros leírás (a registry single-source-ból). */
+    handleList(category) {
+        const descriptors = fam_capability_registry_service_1.FAM_CapabilityRegistry.getInstance().list(category);
+        const byCategory = {};
+        for (const descriptor of descriptors) {
+            const bucket = byCategory[descriptor.category] ?? [];
+            bucket.push({
+                name: descriptor.name,
+                description: descriptor.description,
+                lateBound: descriptor.lateBound === true,
+            });
+            byCategory[descriptor.category] = bucket;
+        }
+        return { categories: byCategory, total: descriptors.length };
+    }
+    /** `describe(name)` → a cél-eszköz teljes input-schema-ja + meta. Ismeretlen → `FAM-MCP-DISPATCH-002`. */
+    handleDescribe(name) {
+        const descriptor = this.requireDescriptor(name, 'capabilities-describe');
+        return {
+            name: descriptor.name,
+            category: descriptor.category,
+            description: descriptor.description,
+            inputSchema: descriptor.inputSchema,
+            lateBound: descriptor.lateBound === true,
+            pendingMp: descriptor.pendingMp,
+        };
+    }
+    /** `invoke(name, arguments)` → a capability handler futtatása. Ismeretlen → `FAM-MCP-DISPATCH-002`. */
+    async handleInvoke(name, args) {
+        const descriptor = this.requireDescriptor(name, 'capabilities-invoke');
+        const outcome = await descriptor.handler(args);
+        return outcome.data;
+    }
+    /** A cél-deszkriptor a nevéből; hiányzó/ismeretlen → `FAM-MCP-DISPATCH-002` (deskriptív). */
+    requireDescriptor(name, operation) {
+        if (!name) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: 'A `describe`/`invoke` action `name`-et igényel (a cél capability-eszköz neve). '
+                    + 'Használd a `list` action-t a katalógus felderítéséhez.',
+                issuer: this.issuer,
+                context: { operation: operation },
+            });
+        }
+        const descriptor = fam_capability_registry_service_1.FAM_CapabilityRegistry.getInstance().get(name);
+        if (!descriptor) {
+            const known = fam_capability_registry_service_1.FAM_CapabilityRegistry.getInstance().names();
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.mcpDispatchUnknownCapability,
+                message: `Ismeretlen capability: '${name}'. Elérhető (${known.length}): ${known.slice(0, 12).join(', ')}…. `
+                    + 'Használd a `capabilities { action: "list" }`-et a teljes katalógushoz.',
+                issuer: this.issuer,
+                context: { operation: operation },
+            });
+        }
+        return descriptor;
+    }
+}
+exports.FAM_CapabilitiesTool_Service = FAM_CapabilitiesTool_Service;