@carlonicora/nestjs-neo4jsonapi 1.62.7 → 1.63.0

package/dist/foundations/assistant/repositories/assistant.repository.d.ts

@@ -0,0 +1,50 @@
+import { ClsService } from "nestjs-cls";
+import { AbstractRepository } from "../../../core/neo4j/abstracts/abstract.repository";
+import { Neo4jService } from "../../../core/neo4j/services/neo4j.service";
+import { SecurityService } from "../../../core/security/services/security.service";
+import { Assistant, AssistantDescriptor } from "../entities/assistant";
+/**
+ * AssistantRepository
+ *
+ * Extends the standard company-scoped match with an additional owner check —
+ * a user can only see/modify assistants they created.
+ *
+ * The `$currentUserId` parameter is auto-injected into queryParams by
+ * `Neo4jService.initQuery()` (reads `clsService.get("userId")`), so the
+ * `buildUserHasAccess` override can reference `$currentUserId` directly.
+ */
+export declare class AssistantRepository extends AbstractRepository<Assistant, typeof AssistantDescriptor.relationships> {
+    protected readonly descriptor: import("../../..").EntityDescriptor<Assistant, {
+        owner: {
+            model: import("../../..").DataMeta;
+            direction: "out";
+            relationship: string;
+            cardinality: "one";
+            required: false;
+            dtoKey: string;
+            contextKey: string;
+            immutable: true;
+        };
+        messages: {
+            model: import("../../..").DataMeta;
+            direction: "out";
+            relationship: string;
+            cardinality: "many";
+            required: false;
+            dtoKey: string;
+        };
+    }>;
+    constructor(neo4j: Neo4jService, securityService: SecurityService, clsService: ClsService);
+    protected buildUserHasAccess(): string;
+    /**
+     * Override delete to cascade through HAS_MESSAGE children so that
+     * `AssistantMessage` nodes (and their REFERENCES edges) are removed with
+     * the parent Assistant. DETACH DELETE drops every relationship incident to
+     * the deleted nodes — including outgoing REFERENCES edges — without
+     * affecting the referenced domain entities.
+     */
+    delete(params: {
+        id: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=assistant.repository.d.ts.map

package/dist/foundations/assistant/repositories/assistant.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/assistant/repositories/assistant.repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEvE;;;;;;;;;GASG;AACH,qBACa,mBAAoB,SAAQ,kBAAkB,CAAC,SAAS,EAAE,OAAO,mBAAmB,CAAC,aAAa,CAAC;IAC9G,SAAS,CAAC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;;;;;;OAAuB;gBAExC,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU;IAIzF,SAAS,CAAC,kBAAkB,IAAI,MAAM;IAStC;;;;;;OAMG;IACG,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAUpD"}

package/dist/foundations/assistant/repositories/assistant.repository.js

@@ -0,0 +1,65 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssistantRepository = void 0;
+const common_1 = require("@nestjs/common");
+const nestjs_cls_1 = require("nestjs-cls");
+const abstract_repository_1 = require("../../../core/neo4j/abstracts/abstract.repository");
+const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
+const security_service_1 = require("../../../core/security/services/security.service");
+const assistant_1 = require("../entities/assistant");
+/**
+ * AssistantRepository
+ *
+ * Extends the standard company-scoped match with an additional owner check —
+ * a user can only see/modify assistants they created.
+ *
+ * The `$currentUserId` parameter is auto-injected into queryParams by
+ * `Neo4jService.initQuery()` (reads `clsService.get("userId")`), so the
+ * `buildUserHasAccess` override can reference `$currentUserId` directly.
+ */
+let AssistantRepository = class AssistantRepository extends abstract_repository_1.AbstractRepository {
+    constructor(neo4j, securityService, clsService) {
+        super(neo4j, securityService, clsService);
+        this.descriptor = assistant_1.AssistantDescriptor;
+    }
+    buildUserHasAccess() {
+        const { nodeName } = this.descriptor.model;
+        return `WITH ${nodeName}
+            WHERE EXISTS {
+              MATCH (${nodeName})-[:CREATED_BY]->(:User {id: $currentUserId})
+            }
+            WITH ${nodeName}`;
+    }
+    /**
+     * Override delete to cascade through HAS_MESSAGE children so that
+     * `AssistantMessage` nodes (and their REFERENCES edges) are removed with
+     * the parent Assistant. DETACH DELETE drops every relationship incident to
+     * the deleted nodes — including outgoing REFERENCES edges — without
+     * affecting the referenced domain entities.
+     */
+    async delete(params) {
+        await this.neo4j.writeOne({
+            query: `
+        MATCH (a:Assistant {id: $id})
+        OPTIONAL MATCH (a)-[:HAS_MESSAGE]->(m:AssistantMessage)
+        DETACH DELETE a, m
+      `,
+            queryParams: { id: params.id },
+        });
+    }
+};
+exports.AssistantRepository = AssistantRepository;
+exports.AssistantRepository = AssistantRepository = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [neo4j_service_1.Neo4jService, security_service_1.SecurityService, nestjs_cls_1.ClsService])
+], AssistantRepository);
+//# sourceMappingURL=assistant.repository.js.map

package/dist/foundations/assistant/repositories/assistant.repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.repository.js","sourceRoot":"","sources":["../../../../src/foundations/assistant/repositories/assistant.repository.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,2CAAwC;AACxC,2FAAuF;AACvF,8EAA0E;AAC1E,uFAAmF;AACnF,qDAAuE;AAEvE;;;;;;;;;GASG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAoB,SAAQ,wCAAuE;IAG9G,YAAY,KAAmB,EAAE,eAAgC,EAAE,UAAsB;QACvF,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,CAAC,CAAC;QAHzB,eAAU,GAAG,+BAAmB,CAAC;IAIpD,CAAC;IAES,kBAAkB;QAC1B,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAC3C,OAAO,QAAQ,QAAQ;;uBAEJ,QAAQ;;mBAEZ,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,MAAsB;QACjC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;YACxB,KAAK,EAAE;;;;OAIN;YACD,WAAW,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAjCY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;qCAIQ,4BAAY,EAAmB,kCAAe,EAAc,uBAAU;GAH9E,mBAAmB,CAiC/B"}

package/dist/foundations/assistant/services/assistant.service.d.ts

@@ -0,0 +1,113 @@
+import { ClsService } from "nestjs-cls";
+import { ChatbotService } from "../../../agents/chatbot/services/chatbot.service";
+import { GraphCatalogService } from "../../../agents/chatbot/services/graph.catalog.service";
+import { UserModulesRepository } from "../../../agents/chatbot/repositories/user-modules.repository";
+import { ChatbotToolCall } from "../../../agents/chatbot/interfaces/chatbot.response.interface";
+import { EntityServiceRegistry } from "../../../common/registries/entity.service.registry";
+import { JsonApiService } from "../../../core/jsonapi/services/jsonapi.service";
+import { AbstractService } from "../../../core/neo4j/abstracts/abstract.service";
+import { AssistantMessage } from "../../assistant-message/entities/assistant-message";
+import { AssistantMessageRepository } from "../../assistant-message/repositories/assistant-message.repository";
+import { AssistantMessageService } from "../../assistant-message/services/assistant-message.service";
+import { Assistant, AssistantDescriptor } from "../entities/assistant";
+import { AssistantRepository } from "../repositories/assistant.repository";
+/**
+ * Maximum number of prior messages (turns) passed to the LLM on each turn.
+ * Keeps prompt size and cost bounded for long conversations.
+ */
+export declare const MAX_MESSAGES_TO_LLM = 20;
+/**
+ * AssistantService
+ *
+ * Wraps the stateless ChatbotService.run() in a stateful lifecycle. Extends
+ * AbstractService so standard CRUD (find / findById / patch / delete) is
+ * inherited and wired through the framework's JSON:API pipeline — only the
+ * agent-turn methods below are bespoke:
+ *   - `createWithFirstMessage` — persists a brand-new assistant thread with the first turn.
+ *   - `appendMessage` — appends a user turn + agent turn to an existing assistant thread.
+ *
+ * Messages are stored as first-class `AssistantMessage` nodes linked via
+ * `(Assistant)-[:HAS_MESSAGE]->(AssistantMessage)`. Per-turn `references` are
+ * materialised as `(AssistantMessage)-[:REFERENCES]->(entity)` edges (see
+ * AssistantMessageRepository.linkReferences).
+ */
+export declare class AssistantService extends AbstractService<Assistant, typeof AssistantDescriptor.relationships> {
+    private readonly userModuleIdsRepository;
+    private readonly chatbot;
+    private readonly assistantMessages;
+    private readonly assistantMessageRepo;
+    private readonly graphCatalog;
+    private readonly entityServices;
+    protected readonly descriptor: import("../../..").EntityDescriptor<Assistant, {
+        owner: {
+            model: import("../../..").DataMeta;
+            direction: "out";
+            relationship: string;
+            cardinality: "one";
+            required: false;
+            dtoKey: string;
+            contextKey: string;
+            immutable: true;
+        };
+        messages: {
+            model: import("../../..").DataMeta;
+            direction: "out";
+            relationship: string;
+            cardinality: "many";
+            required: false;
+            dtoKey: string;
+        };
+    }>;
+    private readonly assistantLogger;
+    constructor(jsonApiService: JsonApiService, assistantRepository: AssistantRepository, clsService: ClsService, userModuleIdsRepository: UserModulesRepository, chatbot: ChatbotService, assistantMessages: AssistantMessageService, assistantMessageRepo: AssistantMessageRepository, graphCatalog: GraphCatalogService, entityServices: EntityServiceRegistry);
+    createWithFirstMessage(params: {
+        companyId: string;
+        userId: string;
+        firstMessage: string;
+        title?: string;
+    }): Promise<{
+        assistant: Assistant;
+        userMessage: AssistantMessage;
+        assistantMessage: AssistantMessage;
+        toolCalls: ChatbotToolCall[];
+    }>;
+    appendMessage(params: {
+        assistantId: string;
+        companyId: string;
+        userId: string;
+        newMessage: string;
+    }): Promise<{
+        userMessage: AssistantMessage;
+        assistantMessage: AssistantMessage;
+        toolCalls: ChatbotToolCall[];
+    }>;
+    /**
+     * Load the most recent N messages for an Assistant, ordered chronologically
+     * (position ASC). Used to build the LLM prompt without pulling full history.
+     */
+    private loadRecentMessages;
+    /**
+     * Runs a single agent turn. Builds a message list of:
+     *   [ optional reference-memory system message, ...prior messages, new user message ]
+     * and invokes the stateless chatbot. Returns the assistant reply metadata.
+     */
+    private runAgentTurn;
+    /**
+     * Two-tier hydration:
+     *   - Focus: full records re-read for every {type,id} referenced by the most
+     *     recent assistant message.
+     *   - Background: id + label stubs for references from earlier messages.
+     * Returns null when there is nothing to hydrate. On any unexpected error
+     * the whole builder returns null so a single bad Neo4j hiccup does not
+     * fail the chat turn.
+     */
+    private buildHydrationMessage;
+    private loadFocusRecords;
+    private loadBackgroundStubs;
+    /**
+     * Auto-generate a title from the first user message: trim to 60 chars on a
+     * word boundary. Falls back to a hard 60-char cut if no suitable break exists.
+     */
+    private autoTitle;
+}
+//# sourceMappingURL=assistant.service.d.ts.map

package/dist/foundations/assistant/services/assistant.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.service.d.ts","sourceRoot":"","sources":["../../../../src/foundations/assistant/services/assistant.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,kDAAkD,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,wDAAwD,CAAC;AAC7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,8DAA8D,CAAC;AACrG,OAAO,EAAoB,eAAe,EAAE,MAAM,+DAA+D,CAAC;AAClH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,gDAAgD,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAA8B,MAAM,oDAAoD,CAAC;AAElH,OAAO,EAAE,0BAA0B,EAAE,MAAM,mEAAmE,CAAC;AAC/G,OAAO,EAAE,uBAAuB,EAAE,MAAM,4DAA4D,CAAC;AACrG,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAiBtC;;;;;;;;;;;;;;GAcG;AACH,qBACa,gBAAiB,SAAQ,eAAe,CAAC,SAAS,EAAE,OAAO,mBAAmB,CAAC,aAAa,CAAC;IAQtG,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAZjC,SAAS,CAAC,QAAQ,CAAC,UAAU;;;;;;;;;;;;;;;;;;;OAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;gBAGnE,cAAc,EAAE,cAAc,EAC9B,mBAAmB,EAAE,mBAAmB,EACxC,UAAU,EAAE,UAAU,EACL,uBAAuB,EAAE,qBAAqB,EAC9C,OAAO,EAAE,cAAc,EACvB,iBAAiB,EAAE,uBAAuB,EAC1C,oBAAoB,EAAE,0BAA0B,EAChD,YAAY,EAAE,mBAAmB,EACjC,cAAc,EAAE,qBAAqB;IAKlD,sBAAsB,CAAC,MAAM,EAAE;QACnC,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QACV,SAAS,EAAE,SAAS,CAAC;QACrB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,SAAS,EAAE,eAAe,EAAE,CAAC;KAC9B,CAAC;IAgFI,aAAa,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACnH,WAAW,EAAE,gBAAgB,CAAC;QAC9B,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,SAAS,EAAE,eAAe,EAAE,CAAC;KAC9B,CAAC;IA4EF;;;OAGG;YACW,kBAAkB;IAUhC;;;;OAIG;YACW,YAAY;IAuC1B;;;;;;;;OAQG;YACW,qBAAqB;YAmFrB,gBAAgB;YAwBhB,mBAAmB;IAuBjC;;;OAGG;IACH,OAAO,CAAC,SAAS;CAOlB"}

package/dist/foundations/assistant/services/assistant.service.js

@@ -0,0 +1,395 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var AssistantService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssistantService = exports.MAX_MESSAGES_TO_LLM = void 0;
+const common_1 = require("@nestjs/common");
+const crypto_1 = require("crypto");
+const nestjs_cls_1 = require("nestjs-cls");
+const chatbot_service_1 = require("../../../agents/chatbot/services/chatbot.service");
+const graph_catalog_service_1 = require("../../../agents/chatbot/services/graph.catalog.service");
+const user_modules_repository_1 = require("../../../agents/chatbot/repositories/user-modules.repository");
+const entity_service_registry_1 = require("../../../common/registries/entity.service.registry");
+const jsonapi_service_1 = require("../../../core/jsonapi/services/jsonapi.service");
+const abstract_service_1 = require("../../../core/neo4j/abstracts/abstract.service");
+const assistant_message_1 = require("../../assistant-message/entities/assistant-message");
+const assistant_message_meta_1 = require("../../assistant-message/entities/assistant-message.meta");
+const assistant_message_repository_1 = require("../../assistant-message/repositories/assistant-message.repository");
+const assistant_message_service_1 = require("../../assistant-message/services/assistant-message.service");
+const assistant_1 = require("../entities/assistant");
+const assistant_meta_1 = require("../entities/assistant.meta");
+const assistant_repository_1 = require("../repositories/assistant.repository");
+/**
+ * Maximum number of prior messages (turns) passed to the LLM on each turn.
+ * Keeps prompt size and cost bounded for long conversations.
+ */
+exports.MAX_MESSAGES_TO_LLM = 20;
+/**
+ * AssistantService
+ *
+ * Wraps the stateless ChatbotService.run() in a stateful lifecycle. Extends
+ * AbstractService so standard CRUD (find / findById / patch / delete) is
+ * inherited and wired through the framework's JSON:API pipeline — only the
+ * agent-turn methods below are bespoke:
+ *   - `createWithFirstMessage` — persists a brand-new assistant thread with the first turn.
+ *   - `appendMessage` — appends a user turn + agent turn to an existing assistant thread.
+ *
+ * Messages are stored as first-class `AssistantMessage` nodes linked via
+ * `(Assistant)-[:HAS_MESSAGE]->(AssistantMessage)`. Per-turn `references` are
+ * materialised as `(AssistantMessage)-[:REFERENCES]->(entity)` edges (see
+ * AssistantMessageRepository.linkReferences).
+ */
+let AssistantService = AssistantService_1 = class AssistantService extends abstract_service_1.AbstractService {
+    constructor(jsonApiService, assistantRepository, clsService, userModuleIdsRepository, chatbot, assistantMessages, assistantMessageRepo, graphCatalog, entityServices) {
+        super(jsonApiService, assistantRepository, clsService, assistant_1.AssistantDescriptor.model);
+        this.userModuleIdsRepository = userModuleIdsRepository;
+        this.chatbot = chatbot;
+        this.assistantMessages = assistantMessages;
+        this.assistantMessageRepo = assistantMessageRepo;
+        this.graphCatalog = graphCatalog;
+        this.entityServices = entityServices;
+        this.descriptor = assistant_1.AssistantDescriptor;
+        this.assistantLogger = new common_1.Logger(AssistantService_1.name);
+    }
+    async createWithFirstMessage(params) {
+        const userModuleIds = await this.userModuleIdsRepository.findModuleIdsForUser(params.userId);
+        const title = params.title?.trim() || this.autoTitle(params.firstMessage);
+        const assistantId = (0, crypto_1.randomUUID)();
+        const userMessageId = (0, crypto_1.randomUUID)();
+        // 1. Create the Assistant (owner edge attached from CLS via contextKey).
+        await this.createFromDTO({
+            data: {
+                type: assistant_meta_1.assistantMeta.type,
+                id: assistantId,
+                attributes: { title },
+            },
+        });
+        // 2. Create the first user message at position 0.
+        await this.assistantMessages.createFromDTO({
+            data: {
+                type: assistant_message_meta_1.assistantMessageMeta.type,
+                id: userMessageId,
+                attributes: {
+                    role: "user",
+                    content: params.firstMessage,
+                    position: 0,
+                },
+                relationships: {
+                    assistant: { data: { type: assistant_meta_1.assistantMeta.type, id: assistantId } },
+                },
+            },
+        });
+        const userMessage = await this.assistantMessageRepo.findById({ id: userMessageId });
+        // 3. Run the agent turn using the just-created user message as context.
+        const turn = await this.runAgentTurn({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds,
+            priorMessages: [],
+            newUserMessage: { role: "user", content: params.firstMessage },
+            assistantId,
+        });
+        // 4. Create the assistant message at position 1 with denormalised references JSON.
+        const assistantMessageId = turn.id;
+        await this.assistantMessages.createFromDTO({
+            data: {
+                type: assistant_message_meta_1.assistantMessageMeta.type,
+                id: assistantMessageId,
+                attributes: {
+                    role: "assistant",
+                    content: turn.content,
+                    position: 1,
+                    suggestedQuestions: turn.suggestedQuestions,
+                    inputTokens: turn.tokens.input,
+                    outputTokens: turn.tokens.output,
+                },
+                relationships: {
+                    assistant: { data: { type: assistant_meta_1.assistantMeta.type, id: assistantId } },
+                },
+            },
+        });
+        // 5. Materialise REFERENCES edges (no-op when references is empty).
+        if (turn.references.length) {
+            await this.assistantMessageRepo.linkReferences({
+                messageId: assistantMessageId,
+                references: turn.references,
+            });
+        }
+        const assistantMessage = await this.assistantMessageRepo.findById({ id: assistantMessageId });
+        this.assistantLogger.log(`createWithFirstMessage: id=${assistantId} userId=${params.userId} companyId=${params.companyId} titleLength=${title.length}`);
+        const assistant = await this.repository.findById({ id: assistantId });
+        return { assistant, userMessage, assistantMessage, toolCalls: turn.toolCalls };
+    }
+    async appendMessage(params) {
+        // Verify ownership via the owner-RBAC-enforcing findById.
+        await this.repository.findById({ id: params.assistantId });
+        const userModuleIds = await this.userModuleIdsRepository.findModuleIdsForUser(params.userId);
+        // Load prior messages for agent context.
+        const priorMessages = await this.loadRecentMessages({
+            assistantId: params.assistantId,
+            limit: exports.MAX_MESSAGES_TO_LLM,
+        });
+        const nextPosition = await this.assistantMessageRepo.getNextPosition({
+            assistantId: params.assistantId,
+        });
+        const userMessageId = (0, crypto_1.randomUUID)();
+        await this.assistantMessages.createFromDTO({
+            data: {
+                type: assistant_message_meta_1.assistantMessageMeta.type,
+                id: userMessageId,
+                attributes: {
+                    role: "user",
+                    content: params.newMessage,
+                    position: nextPosition,
+                },
+                relationships: {
+                    assistant: { data: { type: assistant_meta_1.assistantMeta.type, id: params.assistantId } },
+                },
+            },
+        });
+        const userMessage = await this.assistantMessageRepo.findById({ id: userMessageId });
+        const turn = await this.runAgentTurn({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds,
+            priorMessages,
+            newUserMessage: { role: "user", content: params.newMessage },
+            assistantId: params.assistantId,
+        });
+        const assistantMessageId = turn.id;
+        await this.assistantMessages.createFromDTO({
+            data: {
+                type: assistant_message_meta_1.assistantMessageMeta.type,
+                id: assistantMessageId,
+                attributes: {
+                    role: "assistant",
+                    content: turn.content,
+                    position: nextPosition + 1,
+                    suggestedQuestions: turn.suggestedQuestions,
+                    inputTokens: turn.tokens.input,
+                    outputTokens: turn.tokens.output,
+                },
+                relationships: {
+                    assistant: { data: { type: assistant_meta_1.assistantMeta.type, id: params.assistantId } },
+                },
+            },
+        });
+        if (turn.references.length) {
+            await this.assistantMessageRepo.linkReferences({
+                messageId: assistantMessageId,
+                references: turn.references,
+            });
+        }
+        const assistantMessage = await this.assistantMessageRepo.findById({ id: assistantMessageId });
+        this.assistantLogger.log(`appendMessage: id=${params.assistantId} userId=${params.userId} newPos=${nextPosition}-${nextPosition + 1}`);
+        return { userMessage, assistantMessage, toolCalls: turn.toolCalls };
+    }
+    /**
+     * Load the most recent N messages for an Assistant, ordered chronologically
+     * (position ASC). Used to build the LLM prompt without pulling full history.
+     */
+    async loadRecentMessages(params) {
+        const all = await this.assistantMessageRepo.findByRelated({
+            relationship: assistant_message_1.AssistantMessageDescriptor.relationshipKeys.assistant,
+            id: params.assistantId,
+            cursor: { limit: params.limit },
+            orderBy: "position DESC",
+        });
+        return all.slice(0, params.limit).reverse();
+    }
+    /**
+     * Runs a single agent turn. Builds a message list of:
+     *   [ optional reference-memory system message, ...prior messages, new user message ]
+     * and invokes the stateless chatbot. Returns the assistant reply metadata.
+     */
+    async runAgentTurn(params) {
+        const hydrationContent = await this.buildHydrationMessage(params.priorMessages, params.userModuleIds);
+        const trimmed = params.priorMessages.slice(-exports.MAX_MESSAGES_TO_LLM).map((m) => ({
+            role: m.role,
+            content: m.content,
+        }));
+        const messages = [
+            ...(hydrationContent ? [{ role: "system", content: hydrationContent }] : []),
+            ...trimmed,
+            { role: params.newUserMessage.role, content: params.newUserMessage.content },
+        ];
+        const response = await this.chatbot.run({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds: params.userModuleIds,
+            messages,
+            assistantId: params.assistantId,
+        });
+        return {
+            id: (0, crypto_1.randomUUID)(),
+            role: "assistant",
+            content: response.answer,
+            createdAt: new Date().toISOString(),
+            references: response.references ?? [],
+            suggestedQuestions: response.suggestedQuestions ?? [],
+            tokens: response.tokens ?? { input: 0, output: 0 },
+            toolCalls: response.toolCalls ?? [],
+        };
+    }
+    /**
+     * Two-tier hydration:
+     *   - Focus: full records re-read for every {type,id} referenced by the most
+     *     recent assistant message.
+     *   - Background: id + label stubs for references from earlier messages.
+     * Returns null when there is nothing to hydrate. On any unexpected error
+     * the whole builder returns null so a single bad Neo4j hiccup does not
+     * fail the chat turn.
+     */
+    async buildHydrationMessage(messages, userModuleIds) {
+        if (messages.length === 0)
+            return null;
+        try {
+            const pairs = await this.assistantMessageRepo.findReferencedTypeIdPairs({
+                messageIds: messages.map((m) => m.id),
+            });
+            if (pairs.length === 0)
+                return null;
+            // The most recent assistant message is the focus anchor.
+            const prevAssistantId = [...messages].reverse().find((m) => m.role === "assistant")?.id;
+            // Partition references into focus (from previous assistant message) and
+            // background (from any earlier message). Entity dedup on (type,id).
+            const focusKeys = new Set();
+            const backgroundKeys = new Set();
+            const focusRefs = [];
+            const backgroundRefs = [];
+            for (const p of pairs) {
+                const key = `${p.type}/${p.id}`;
+                if (prevAssistantId && p.messageId === prevAssistantId) {
+                    if (!focusKeys.has(key)) {
+                        focusKeys.add(key);
+                        focusRefs.push({ type: p.type, id: p.id });
+                    }
+                }
+                else if (!backgroundKeys.has(key)) {
+                    backgroundKeys.add(key);
+                    backgroundRefs.push({ type: p.type, id: p.id });
+                }
+            }
+            // Anything also in focus must not appear in background.
+            const backgroundOnly = backgroundRefs.filter((b) => !focusKeys.has(`${b.type}/${b.id}`));
+            // Size caps.
+            const FOCUS_CAP = 25;
+            const BACKGROUND_CAP = 100;
+            const focusCapped = focusRefs.slice(0, FOCUS_CAP);
+            if (focusRefs.length > FOCUS_CAP) {
+                this.assistantLogger.warn(`buildHydrationMessage: focus set capped at ${FOCUS_CAP} (had ${focusRefs.length})`);
+            }
+            const backgroundCapped = backgroundOnly.slice(0, BACKGROUND_CAP);
+            if (backgroundOnly.length > BACKGROUND_CAP) {
+                this.assistantLogger.warn(`buildHydrationMessage: background set capped at ${BACKGROUND_CAP} (had ${backgroundOnly.length})`);
+            }
+            // Load focus records (full) and background records (project to label).
+            const focusRecords = await this.loadFocusRecords(focusCapped, userModuleIds);
+            const backgroundStubs = await this.loadBackgroundStubs(backgroundCapped, userModuleIds);
+            if (focusRecords.length === 0 && backgroundStubs.length === 0)
+                return null;
+            const sections = ["## Entities already in this conversation", ""];
+            if (focusRecords.length > 0) {
+                sections.push("### Full records from the previous answer");
+                sections.push('These are the entities your previous answer was about. When the user\'s new question refers to any of them — by name or implicitly ("these", "them", "other orders", "their invoices") — use their id directly. Do not call resolve_entity for a name that matches one of these.');
+                sections.push("");
+                sections.push(JSON.stringify(focusRecords, null, 2));
+                sections.push("");
+            }
+            if (backgroundStubs.length > 0) {
+                sections.push("### Other entities mentioned earlier in this conversation");
+                sections.push("These have been referenced in earlier turns. Recognise them if the user names them, and call read_entity(type, id) if you need their fields again.");
+                sections.push("");
+                for (const s of backgroundStubs) {
+                    sections.push(s.label ? `- ${s.type}/${s.id} — "${s.label}"` : `- ${s.type}/${s.id}`);
+                }
+            }
+            return sections.join("\n");
+        }
+        catch (err) {
+            this.assistantLogger.error(`buildHydrationMessage failed — proceeding without hydration: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err.stack : undefined);
+            return null;
+        }
+    }
+    async loadFocusRecords(refs, userModuleIds) {
+        const out = [];
+        for (const ref of refs) {
+            // Per-type module gate. getEntityDetail returns null when the type is
+            // not accessible to the current userModuleIds.
+            const detail = this.graphCatalog.getEntityDetail(ref.type, userModuleIds);
+            if (!detail)
+                continue;
+            const svc = this.entityServices.get(ref.type);
+            if (!svc)
+                continue;
+            try {
+                const record = await svc.findRecordById({ id: ref.id });
+                if (!record)
+                    continue;
+                out.push({ ...record, type: ref.type });
+            }
+            catch {
+                // Deleted or RBAC-denied: drop silently.
+                continue;
+            }
+        }
+        return out;
+    }
+    async loadBackgroundStubs(refs, userModuleIds) {
+        const out = [];
+        for (const ref of refs) {
+            const detail = this.graphCatalog.getEntityDetail(ref.type, userModuleIds);
+            if (!detail)
+                continue;
+            const labelField = detail.textSearchFields?.[0];
+            const svc = this.entityServices.get(ref.type);
+            if (!svc)
+                continue;
+            try {
+                const record = await svc.findRecordById({ id: ref.id });
+                if (!record)
+                    continue;
+                const label = labelField ? record[labelField] : undefined;
+                out.push({ type: ref.type, id: ref.id, ...(label ? { label } : {}) });
+            }
+            catch {
+                continue;
+            }
+        }
+        return out;
+    }
+    /**
+     * Auto-generate a title from the first user message: trim to 60 chars on a
+     * word boundary. Falls back to a hard 60-char cut if no suitable break exists.
+     */
+    autoTitle(firstMessage) {
+        const trimmed = firstMessage.trim();
+        if (trimmed.length <= 60)
+            return trimmed;
+        const at60 = trimmed.slice(0, 60);
+        const lastSpace = at60.lastIndexOf(" ");
+        return lastSpace > 30 ? at60.slice(0, lastSpace).trim() : at60.trim();
+    }
+};
+exports.AssistantService = AssistantService;
+exports.AssistantService = AssistantService = AssistantService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [jsonapi_service_1.JsonApiService,
+        assistant_repository_1.AssistantRepository,
+        nestjs_cls_1.ClsService,
+        user_modules_repository_1.UserModulesRepository,
+        chatbot_service_1.ChatbotService,
+        assistant_message_service_1.AssistantMessageService,
+        assistant_message_repository_1.AssistantMessageRepository,
+        graph_catalog_service_1.GraphCatalogService,
+        entity_service_registry_1.EntityServiceRegistry])
+], AssistantService);
+//# sourceMappingURL=assistant.service.js.map