@futdevpro/fdp-agent-memory 1.1.134 → 1.1.136

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@futdevpro/fdp-agent-memory",
-    "version": "1.1.134",
+    "version": "1.1.136",
     "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
     "private": false,
     "publishConfig": {

package/build/src/_collections/fam-agent-guidance.util.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_AgentGuidance_Util = exports.FAM_AgentMistake = void 0;
+/**
+ * A felismert agent-hiba osztálya (a guidance + az incidens-rögzítés kulcsa).
+ */
+var FAM_AgentMistake;
+(function (FAM_AgentMistake) {
+    /** A body nem érvényes JSON (a leggyakoribb: aposztróf, lezáró vessző, nem-escape-elt sortörés). */
+    FAM_AgentMistake["malformedJson"] = "malformed-json";
+    /** Üres body egy olyan végponton, ami JSON-t vár. */
+    FAM_AgentMistake["emptyBody"] = "empty-body";
+    /** Nem létező útvonal (elgépelt/kitalált endpoint). */
+    FAM_AgentMistake["unknownEndpoint"] = "unknown-endpoint";
+    /** Rossz HTTP-metódus a létező útvonalon. */
+    FAM_AgentMistake["wrongMethod"] = "wrong-method";
+})(FAM_AgentMistake || (exports.FAM_AgentMistake = FAM_AgentMistake = {}));
+/**
+ * `FAM_AgentGuidance_Util` — **agent-támogató visszajelzések** (user-FR 2026-08-14).
+ *
+ * **A megfigyelt jelenség:** agentek, akiknek elsőre nem sikerült az MCP-t az elvárt módon használni, kerülőúton
+ * NYERS REST-hívásokkal próbálkoznak — és ezek gyakran rosszul összeállítottak (pl. aposztrófos „JSON"). Eddig egy
+ * néma parse-hiba volt a válasz: az agent nem tudta meg, MI a baj, sem azt, hogy MI lett volna a helyes út.
+ *
+ * **A cél (owner-direktíva):** „meg kell fogni a kis kezüket és irányba kell állítani őket — de NEM vehetjük el a
+ * kedvüket attól, hogy használják a FAM-ot; a FAM használata kritikusan fontos lépés MINDIG és MINDENKOR."
+ * Ezért minden üzenet: (1) tényszerűen megmondja mi a baj, (2) megadja a LEGVALÓSZÍNŰBB okot, (3) konkrét javítást,
+ * (4) másolható példát, (5) az ajánlott (MCP) utat, és (6) **megerősíti, hogy jó úton jár** — a hiba csak formai.
+ *
+ * PURE: nincs I/O, nincs állapot — így a szöveg-kontraktus unit-tesztelhető.
+ */
+class FAM_AgentGuidance_Util {
+    /** A `read` tool minimál, helyes hívása (a leggyakoribb szándék). */
+    static READ_EXAMPLE = '{"queries":[{"tables":["knowledge"],"query":"amit keresel","topK":5}]}';
+    /** A `write` tool minimál, helyes hívása. */
+    static WRITE_EXAMPLE = '{"operation":"create","table":"memory","content":"a megjegyzendő tudás","scopePath":[{"layer":"project","name":"<projekt>"}]}';
+    /**
+     * A JSON-parse hiba KONKRÉT okának felismerése a nyers body-ból (PURE). A body-parser üzenete önmagában
+     * (`Expected property name or '}' at position 1`) egy agentnek keveset mond — a tényleges minta viszont
+     * elárulja a tipikus elrontást, és így célzott javítási tanácsot tudunk adni.
+     */
+    static diagnoseJson(rawBody) {
+        const body = (rawBody ?? '').trim();
+        if (!body) {
+            return {
+                mistake: FAM_AgentMistake.emptyBody,
+                likelyCause: 'A kérés törzse ÜRES, pedig ez a végpont JSON-objektumot vár.',
+                howToFix: 'Küldd el a JSON-body-t `Content-Type: application/json` fejléccel.',
+            };
+        }
+        // A leggyakoribb elrontás: aposztróf idézőjel helyett (shell-quoting / Python-szerű dict beillesztése).
+        if (/^\{\s*'/.test(body) || /:\s*'/.test(body)) {
+            return {
+                mistake: FAM_AgentMistake.malformedJson,
+                likelyCause: 'A body APOSZTRÓFOT (\') használ idézőjel (") helyett — ez Python/JS-objektum-szintaxis, '
+                    + 'NEM JSON. Gyakran shell-idézőjel-ütközésből vagy egy nyelvi dict beillesztéséből ered.',
+                howToFix: 'Cseréld az összes aposztrófot kettős idézőjelre; a kulcsokat is idézőjelezd: {"kulcs":"érték"}.',
+            };
+        }
+        if (/,\s*[}\]]/.test(body)) {
+            return {
+                mistake: FAM_AgentMistake.malformedJson,
+                likelyCause: 'LEZÁRÓ VESSZŐ van az utolsó elem után (`…,}` vagy `…,]`) — a JSON ezt nem engedi.',
+                howToFix: 'Töröld a vesszőt az utolsó kulcs/elem után.',
+            };
+        }
+        if (!/^[[{]/.test(body)) {
+            return {
+                mistake: FAM_AgentMistake.malformedJson,
+                likelyCause: 'A body nem `{` vagy `[` karakterrel kezdődik — valószínűleg idézőjelek közé csomagolva '
+                    + 'vagy escape-elve érkezett (dupla-stringify / shell-idézőjel).',
+                howToFix: 'Küldd a NYERS JSON-objektumot, ne stringbe csomagolva (ne `"{\\"a\\":1}"`, hanem `{"a":1}`).',
+            };
+        }
+        return {
+            mistake: FAM_AgentMistake.malformedJson,
+            likelyCause: 'A body szintaktikailag hibás JSON (hiányzó idézőjel/zárójel vagy nem-escape-elt sortörés).',
+            howToFix: 'Ellenőrizd a zárójel-párokat és az idézőjeleket; a többsoros szöveget `\\n`-nel escape-eld.',
+        };
+    }
+    /** Melyik FAM-tool tartozik az útvonalhoz (az „inkább ezt használd" tanácshoz). PURE. */
+    static toolForPath(path) {
+        const url = (path ?? '').toLowerCase();
+        if (url.includes('/read')) {
+            return 'read';
+        }
+        if (url.includes('/write') || url.includes('/scan')) {
+            return 'write';
+        }
+        if (url.includes('/capabilities')) {
+            return 'capabilities';
+        }
+        return null;
+    }
+    /**
+     * A teljes eligazítás összeállítása (PURE). A hangnem KÖTELEZŐEN támogató: a FAM-hoz fordulás MINDIG helyes
+     * döntés volt — csak a kérés formája hibás, és pontosan megmondjuk, hogyan javítsd.
+     */
+    static build(set) {
+        const tool = FAM_AgentGuidance_Util.toolForPath(set.path);
+        const example = tool === 'write' ? FAM_AgentGuidance_Util.WRITE_EXAMPLE : FAM_AgentGuidance_Util.READ_EXAMPLE;
+        const preferred = tool
+            ? `AJÁNLOTT: a nyers REST helyett használd az MCP-toolt — \`mcp__fdp-agent-memory__${tool}\`. Ugyanezt a `
+                + 'bemenetet várja, de a kliens szerializálja helyetted (nincs idézőjel-ütközés), és a hibákat is '
+                + 'olvashatóan adja vissza. Ha az MCP-eszköz nem elérhető, a REST teljes értékű tartalék — csak a '
+                + 'JSON-formára figyelj.'
+            : 'AJÁNLOTT: a FAM felülete a `read` / `write` / `capabilities` — a `capabilities` felsorolja a pontos '
+                + 'bemeneti sémákat. MCP-n át (`mcp__fdp-agent-memory__*`) a legkényelmesebb, de a REST is teljes értékű.';
+        return {
+            mistake: set.mistake,
+            errorCode: FAM_AgentGuidance_Util.errorCodeFor(set.mistake),
+            whatHappened: `A FAM megkapta a kérésedet (${set.method ?? '?'} ${set.path ?? '?'}), de a törzsét nem tudta `
+                + 'JSON-ként értelmezni, ezért NEM hajtotta végre. Semmi nem íródott és nem változott.',
+            likelyCause: set.likelyCause,
+            howToFix: set.howToFix,
+            example: example,
+            preferredApproach: preferred,
+            // A hangnem SZÁNDÉKOS: a következő lépés a ÚJRAPRÓBÁLKOZÁS legyen, nem a FAM elkerülése.
+            encouragement: 'Jó irányba indultál: a FAM-hoz fordulni MINDIG helyes lépés — a tudás ott van, csak a '
+                + 'kérés formája volt hibás. Javítsd a fentiek szerint és próbáld újra; ha elakadsz, a '
+                + '`capabilities` megadja a pontos sémát.',
+        };
+    }
+    /** A hiba-osztályhoz tartozó stabil hibakód (az incidens-rögzítés dedup-kulcsa is). PURE. */
+    static errorCodeFor(mistake) {
+        switch (mistake) {
+            case FAM_AgentMistake.emptyBody:
+                return 'FAM-AGENT-INPUT-002';
+            case FAM_AgentMistake.unknownEndpoint:
+                return 'FAM-AGENT-INPUT-003';
+            case FAM_AgentMistake.wrongMethod:
+                return 'FAM-AGENT-INPUT-004';
+            default:
+                return 'FAM-AGENT-INPUT-001';
+        }
+    }
+}
+exports.FAM_AgentGuidance_Util = FAM_AgentGuidance_Util;

package/build/src/_modules/retrieval/_services/fam-rule-injection.control-service.js

@@ -60,9 +60,46 @@ class FAM_RuleInjection_ControlService {
         // CSAK a rangsorhoz/megjelenítéshez kellő mezők (a vektor NEM kell → könnyű lean-query).
         const docs = await model.find(filter, {
             content: 1, importance: 1, weight: 1, globalRule: 1, category: 1,
-            ruleScope: 1, ruleScopeTopic: 1, ruleId: 1, derivedFrom: 1, __lastModified: 1,
+            ruleScope: 1, ruleScopeTopic: 1, ruleId: 1, derivedFrom: 1, __lastModified: 1, chunkIndex: 1,
         }).lean();
-        return docs.map((doc) => this.toInjectable(doc));
+        return FAM_RuleInjection_ControlService.mergeChunks(docs.map((doc) => this.toInjectable(doc)), docs.map((doc) => (typeof doc.chunkIndex === 'number' ? doc.chunkIndex : 0)));
+    }
+    /**
+     * A TÖBB CHUNKRA bomlott szabályok ÖSSZEFŰZÉSE `ruleId` szerint (2026-08-14 lelet — `core-rule-integrity`).
+     *
+     * **A hiba, amit javít:** a ~1100 karakternél hosszabb rule-fájlok több chunkra bomlanak az ingestkor, és a
+     * budget-fit ezeket KÜLÖN tételként kezelte. Következmény: (a) egy hosszabb szabályból a blokkba VÉLETLENSZERŰ
+     * TÖREDÉK került (mérve: a `core-review-until-clean`-ből csak a 2. fele, így a „két egymást követő tiszta kör"
+     * MAG KIMARADT), (b) ugyanaz a cím KÉTSZER jelent meg, feleslegesen fogyasztva a budget-et. Ez pontosan a
+     * `core-rule-integrity` által TILTOTT néma csonkolás — egy szabály CSAK teljes egészében adható tovább.
+     *
+     * **Megoldás:** `ruleId`-nként egyetlen tétellé fűzzük a chunkokat `chunkIndex` sorrendben. Így a budget-fit
+     * atomi egységként dönt: a szabály vagy TELJESEN bekerül, vagy a „(…and N more rules not shown)" jelzésbe esik —
+     * de SOSEM félig. A `ruleId` nélküli (nem-kurált) bejegyzések érintetlenül maradnak.
+     */
+    static mergeChunks(rules, chunkIndexes) {
+        const byRuleId = new Map();
+        const passthrough = [];
+        rules.forEach((rule, position) => {
+            if (!rule.ruleId) {
+                passthrough.push(rule);
+                return;
+            }
+            const existing = byRuleId.get(rule.ruleId);
+            const part = { index: chunkIndexes[position] ?? 0, content: rule.content ?? '' };
+            if (existing) {
+                existing.parts.push(part);
+                // A legfrissebb módosítás nyer a rangsor-tiebreaknél (a chunkok azonos fájlból jönnek).
+                existing.rule.lastModifiedMs = Math.max(existing.rule.lastModifiedMs ?? 0, rule.lastModifiedMs ?? 0);
+                return;
+            }
+            byRuleId.set(rule.ruleId, { rule: { ...rule }, parts: [part] });
+        });
+        const merged = Array.from(byRuleId.values()).map((entry) => ({
+            ...entry.rule,
+            content: entry.parts.sort((a, b) => a.index - b.index).map((part) => part.content).join('\n'),
+        }));
+        return [...merged, ...passthrough];
     }
     /** Explicit felülírás > `cwd`-detekció. A `projectType`/`topics`/budget mindig az inputból. */
     resolveContext(input) {

package/build/src/app.server.js

@@ -7,6 +7,7 @@ const logs_1 = require("@futdevpro/nts-dynamo/logs");
 const package_json_1 = require("../package.json");
 const fam_db_models_const_1 = require("./_collections/fam-db-models.const");
 const fam_remote_config_util_1 = require("./_collections/fam-remote-config.util");
+const fam_agent_guidance_util_1 = require("./_collections/fam-agent-guidance.util");
 const api_controller_1 = require("./_routes/server/api/api.controller");
 const client_app_controller_1 = require("./_routes/server/client-app/client-app.controller");
 const errors_controller_1 = require("./_routes/server/errors/errors.controller");
@@ -163,6 +164,81 @@ class App extends nts_dynamo_1.DyNTS_App {
         await embedding_1.FAM_EmbeddingBootstrap_ControlService.getInstance().boot();
         fsm_dynamo_1.DyFM_Log.S_info(`UI is available at: localhost:${environment_1.env.httpPort}/api/app`);
     }
+    /**
+     * AGENT-TÁMOGATÁS + ÖNDIAGNOSZTIKA (user-FR 2026-08-14). A bedrock `initOpenExpress` regisztrálja a
+     * body-parsert; KÖZVETLENÜL utána ékeljük be a saját JSON-hiba-kezelőnket, így:
+     * (1) a hibás kérés a **routing előtt** nálunk landol → van teljes kontextusunk (a bedrock-úton elveszne),
+     * (2) az agent **cselekvésre fordítható eligazítást** kap 400-zal (nem néma hibát), és
+     * (3) az esetet **incidensként rögzítjük** (öndiagnosztika: ki, mit, mikor, milyen mintával).
+     *
+     * A megfigyelt jelenség: akinek elsőre nem sikerült az MCP-használat, nyers REST-tel próbálkozik, és a body
+     * gyakran rosszul összeállított (pl. aposztrófos „JSON"). A válasz hangneme SZÁNDÉKOSAN támogató — a cél, hogy
+     * az agent JAVÍTVA ÚJRAPRÓBÁLJA, ne pedig elkerülje a FAM-ot.
+     */
+    async initOpenExpress() {
+        await super.initOpenExpress();
+        this.openExpress?.use(App.jsonErrorMiddleware());
+    }
+    /**
+     * A body-parser JSON-hibáját elkapó Express error-middleware (4 argumentumos — ez teszi error-handlerré).
+     * Csak a PARSE-hibát kezeli; minden más hibát változatlanul továbbad a bedrock láncnak.
+     */
+    static jsonErrorMiddleware() {
+        return (err, req, res, next) => {
+            const isParseError = err instanceof SyntaxError
+                && typeof err.status === 'number'
+                && 'body' in err;
+            if (!isParseError) {
+                next(err);
+                return;
+            }
+            const rawBody = typeof err.body === 'string'
+                ? err.body
+                : undefined;
+            const diagnosis = fam_agent_guidance_util_1.FAM_AgentGuidance_Util.diagnoseJson(rawBody);
+            const guidance = fam_agent_guidance_util_1.FAM_AgentGuidance_Util.build({
+                mistake: diagnosis.mistake, likelyCause: diagnosis.likelyCause, howToFix: diagnosis.howToFix,
+                path: req.originalUrl ?? req.url, method: req.method,
+            });
+            // (3) ÖNDIAGNOSZTIKA: incidens a FAM SAJÁT error-útján (dedup + occurrence-count + REST `/api/errors`),
+            // teljes kontextussal. Fire-and-forget: a diagnosztika SOHA nem késleltetheti/buktathatja a választ.
+            void App.recordAgentIncident(guidance, req, rawBody);
+            // (2) Cselekvésre fordítható válasz — 400 (a hibás kérés NEM 2xx; korábban a bedrock-út 200-at adott).
+            res.status(400).json({ ok: false, error: { errorCode: guidance.errorCode, message: guidance.whatHappened }, guidance: guidance });
+        };
+    }
+    /**
+     * Egy agent-input-incidens rögzítése a `fam_errors` tárba (REUSE: a meglévő emit-út adja a dedupot, az
+     * occurrence-countot és a `/api/errors` felületet — nincs új tár). A kontextus a hívó azonosítóit viszi
+     * (metódus, útvonal, aláírás-headerek) + a hibás body CSONKOLT, sensitive-szűrt mintáját, hogy a minta
+     * felismerhető legyen. Best-effort: sosem dob.
+     */
+    static async recordAgentIncident(guidance, req, rawBody) {
+        try {
+            const headers = (req.headers ?? {});
+            const text = (value) => typeof value === 'string' && value.trim() ? value.trim().slice(0, 120) : undefined;
+            const requestContext = [
+                `${req.method ?? '?'} ${req.originalUrl ?? req.url ?? '?'}`,
+                text(headers['user-agent']) ? `ua=${text(headers['user-agent'])}` : undefined,
+                text(headers['x-fam-agent']) ? `agent=${text(headers['x-fam-agent'])}` : undefined,
+                text(headers['x-fam-session']) ? `session=${text(headers['x-fam-session'])}` : undefined,
+            ].filter(Boolean).join(' · ');
+            await errors_control_service_1.FAM_Error_ControlService.getInstance().emit({
+                errorCode: guidance.errorCode,
+                message: `Agent-input hiba (${guidance.mistake}): ${guidance.likelyCause}`,
+                level: fsm_dynamo_1.DyFM_ErrorLevel.warning,
+                context: {
+                    operation: 'agent-input',
+                    requestContext: requestContext,
+                    // A hibás minta CSONKOLVA — ebből ismerhető fel a visszatérő elrontás; a sensitive-szűrés a factory-ban.
+                    failedSample: rawBody ? rawBody.slice(0, 200) : undefined,
+                },
+            });
+        }
+        catch {
+            // best-effort: az öndiagnosztika sosem buktathatja a kérés-kezelést
+        }
+    }
     /**
      * A hiba `additionalContent`-jének BIZTONSÁGOSSÁ tétele + a kérés azonosítóinak megőrzése (2026-08-13).
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fdp-agent-memory",
-  "version": "1.1.134",
+  "version": "1.1.136",
   "description": "Local-first, vector-backed multi-table agent memory exposed as an MCP server (read/write/capabilities). Public, FDP-Templates-free, no auth.",
   "private": false,
   "publishConfig": {