@carlonicora/nestjs-neo4jsonapi 2.1.0 → 2.3.0

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

@@ -8,6 +8,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 var AssistantService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssistantService = exports.MAX_MESSAGES_TO_LLM = void 0;
@@ -19,9 +22,13 @@ const operator_checkpointer_service_1 = require("../../../agents/operator/servic
 const operator_service_1 = require("../../../agents/operator/services/operator.service");
 const responder_service_1 = require("../../../agents/responder/services/responder.service");
 const graph_catalog_service_1 = require("../../../agents/graph/services/graph.catalog.service");
+const scope_guard_1 = require("../../../agents/graph/services/scope.guard");
 const user_modules_repository_1 = require("../../../agents/graph/repositories/user-modules.repository");
 const agentmessage_type_1 = require("../../../common/enums/agentmessage.type");
+const seed_context_interface_1 = require("../../../common/interfaces/seed.context.interface");
 const entity_service_registry_1 = require("../../../common/registries/entity.service.registry");
+const blocknote_service_1 = require("../../../core/blocknote/services/blocknote.service");
+const jsonapi_paginator_1 = require("../../../core/jsonapi/serialisers/jsonapi.paginator");
 const jsonapi_service_1 = require("../../../core/jsonapi/services/jsonapi.service");
 const abstract_service_1 = require("../../../core/neo4j/abstracts/abstract.service");
 const websocket_service_1 = require("../../../core/websocket/services/websocket.service");
@@ -33,7 +40,9 @@ const assistant_message_repository_1 = require("../../assistant-message/reposito
 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 registry_1 = require("../../../common/registries/registry");
 const assistant_repository_1 = require("../repositories/assistant.repository");
+const assistant_mention_extractor_1 = require("./assistant-mention.extractor");
 /**
  * Maximum number of prior messages (turns) passed to the LLM on each turn.
  * Keeps prompt size and cost bounded for long conversations.
@@ -55,7 +64,7 @@ exports.MAX_MESSAGES_TO_LLM = 20;
  * AssistantMessageRepository.linkReferences).
  */
 let AssistantService = AssistantService_1 = class AssistantService extends abstract_service_1.AbstractService {
-    constructor(jsonApiService, assistantRepository, clsService, userModuleIdsRepository, responder, assistantMessages, assistantMessageRepo, graphCatalog, entityServices, operator, assistantActions, assistantActionRepo, webSocketService, configService) {
+    constructor(jsonApiService, assistantRepository, clsService, userModuleIdsRepository, responder, assistantMessages, assistantMessageRepo, graphCatalog, entityServices, operator, assistantActions, assistantActionRepo, webSocketService, configService, mentions, blockNote, scopeGuard, seedContextProviders) {
         super(jsonApiService, assistantRepository, clsService, assistant_1.AssistantDescriptor.model);
         this.userModuleIdsRepository = userModuleIdsRepository;
         this.responder = responder;
@@ -68,15 +77,31 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
         this.assistantActionRepo = assistantActionRepo;
         this.webSocketService = webSocketService;
         this.configService = configService;
+        this.mentions = mentions;
+        this.blockNote = blockNote;
+        this.scopeGuard = scopeGuard;
+        this.seedContextProviders = seedContextProviders;
         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 ctx = this.buildTurnContext({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds,
+            boundContent: params.boundContent,
+        });
+        const { content: firstMessage, plainText, pinned, } = await this.resolveUserTurnInput({
+            rawContent: params.firstMessage,
+            ctx,
+        });
+        const title = params.title?.trim() || this.autoTitle(plainText);
         const assistantId = (0, crypto_1.randomUUID)();
         const userMessageId = (0, crypto_1.randomUUID)();
         // 1. Create the Assistant (owner edge attached from CLS via contextKey).
+        //    A bound thread also gets the BOUND_TO edge to the resource it is
+        //    confined to — the relationship is immutable, so it is set on create.
         await this.createFromDTO({
             data: {
                 type: assistant_meta_1.assistantMeta.type,
@@ -84,6 +109,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 attributes: { title },
             },
         });
+        await this.attachBoundContent(assistantId, params.boundContent);
         // 2. Create the first user message at position 0.
         await this.assistantMessages.createFromDTO({
             data: {
@@ -91,7 +117,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 id: userMessageId,
                 attributes: {
                     role: "user",
-                    content: params.firstMessage,
+                    content: firstMessage,
                     position: 0,
                 },
                 relationships: {
@@ -99,15 +125,16 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 },
             },
         });
+        await this.linkPinnedMentions({ messageId: userMessageId, pinned });
         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,
+            ctx,
             priorMessages: [],
-            newUserMessage: { role: "user", content: params.firstMessage },
+            newUserMessage: { role: "user", content: firstMessage },
+            pinned,
             assistantId,
+            contentScope: this.toContentScope(params.boundContent),
             howToMode: params.howToMode,
             limitToHowToId: params.limitToHowToId,
         });
@@ -156,6 +183,18 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
         // Verify ownership via the owner-RBAC-enforcing findById.
         await this.repository.findById({ id: params.assistantId });
         const userModuleIds = await this.userModuleIdsRepository.findModuleIdsForUser(params.userId);
+        // An append inherits the thread's binding — never a client-supplied one.
+        const contentScope = await this.resolveContentScope(params.assistantId);
+        const ctx = this.buildTurnContext({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds,
+            boundContent: this.toBoundContent(contentScope),
+        });
+        const { content: newMessage, pinned } = await this.resolveUserTurnInput({
+            rawContent: params.newMessage,
+            ctx,
+        });
         // Load prior messages for agent context.
         const priorMessages = await this.loadRecentMessages({
             assistantId: params.assistantId,
@@ -171,7 +210,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 id: userMessageId,
                 attributes: {
                     role: "user",
-                    content: params.newMessage,
+                    content: newMessage,
                     position: nextPosition,
                 },
                 relationships: {
@@ -179,14 +218,15 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 },
             },
         });
+        await this.linkPinnedMentions({ messageId: userMessageId, pinned });
         const userMessage = await this.assistantMessageRepo.findById({ id: userMessageId });
         const turn = await this.runAgentTurn({
-            companyId: params.companyId,
-            userId: params.userId,
-            userModuleIds,
+            ctx,
             priorMessages,
-            newUserMessage: { role: "user", content: params.newMessage },
+            newUserMessage: { role: "user", content: newMessage },
+            pinned,
             assistantId: params.assistantId,
+            contentScope,
             howToMode: params.howToMode,
             limitToHowToId: params.limitToHowToId,
         });
@@ -237,7 +277,17 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
      */
     async createWithFirstMessageOperator(params) {
         const userModuleIds = await this.userModuleIdsRepository.findModuleIdsForUser(params.userId);
-        const title = params.title?.trim() || this.autoTitle(params.firstMessage);
+        const ctx = this.buildTurnContext({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds,
+            boundContent: params.boundContent,
+        });
+        const { content: firstMessage, plainText, pinned, } = await this.resolveUserTurnInput({
+            rawContent: params.firstMessage,
+            ctx,
+        });
+        const title = params.title?.trim() || this.autoTitle(plainText);
         const assistantId = (0, crypto_1.randomUUID)();
         const userMessageId = (0, crypto_1.randomUUID)();
         // Persist the engine marker so clients can route follow-up turns to the
@@ -247,6 +297,13 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 type: assistant_meta_1.assistantMeta.type,
                 id: assistantId,
                 attributes: { title, engine: "operator" },
+                ...(params.boundContent
+                    ? {
+                        relationships: {
+                            content: { data: { type: params.boundContent.type, id: params.boundContent.id } },
+                        },
+                    }
+                    : {}),
             },
         });
         await this.assistantMessages.createFromDTO({
@@ -255,7 +312,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 id: userMessageId,
                 attributes: {
                     role: "user",
-                    content: params.firstMessage,
+                    content: firstMessage,
                     position: 0,
                 },
                 relationships: {
@@ -263,18 +320,20 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 },
             },
         });
+        await this.linkPinnedMentions({ messageId: userMessageId, pinned });
         const userMessage = await this.assistantMessageRepo.findById({ id: userMessageId });
         const threadId = `${assistantId}:${userMessageId}`;
-        const contentScope = await this.resolveContentScope(assistantId);
+        const contentScope = this.toContentScope(params.boundContent);
         const result = await this.runOperatorTurn({
-            companyId: params.companyId,
-            userId: params.userId,
-            userModuleIds,
+            ctx,
             priorMessages: [],
-            question: params.firstMessage,
+            question: firstMessage,
+            pinned,
             assistantId,
             threadId,
             contentScope,
+            howToMode: params.howToMode,
+            limitToHowToId: params.limitToHowToId,
         });
         const outcome = await this.persistOperatorOutcome({
             assistantId,
@@ -296,6 +355,17 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
         // Verify ownership via the owner-RBAC-enforcing findById.
         await this.repository.findById({ id: params.assistantId });
         const userModuleIds = await this.userModuleIdsRepository.findModuleIdsForUser(params.userId);
+        const contentScope = await this.resolveContentScope(params.assistantId);
+        const ctx = this.buildTurnContext({
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds,
+            boundContent: this.toBoundContent(contentScope),
+        });
+        const { content: newMessage, pinned } = await this.resolveUserTurnInput({
+            rawContent: params.newMessage,
+            ctx,
+        });
         const priorMessages = await this.loadRecentMessages({
             assistantId: params.assistantId,
             limit: exports.MAX_MESSAGES_TO_LLM,
@@ -310,7 +380,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 id: userMessageId,
                 attributes: {
                     role: "user",
-                    content: params.newMessage,
+                    content: newMessage,
                     position: nextPosition,
                 },
                 relationships: {
@@ -318,18 +388,19 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 },
             },
         });
+        await this.linkPinnedMentions({ messageId: userMessageId, pinned });
         const userMessage = await this.assistantMessageRepo.findById({ id: userMessageId });
         const threadId = `${params.assistantId}:${userMessageId}`;
-        const contentScope = await this.resolveContentScope(params.assistantId);
         const result = await this.runOperatorTurn({
-            companyId: params.companyId,
-            userId: params.userId,
-            userModuleIds,
+            ctx,
             priorMessages,
-            question: params.newMessage,
+            question: newMessage,
+            pinned,
             assistantId: params.assistantId,
             threadId,
             contentScope,
+            howToMode: params.howToMode,
+            limitToHowToId: params.limitToHowToId,
         });
         const outcome = await this.persistOperatorOutcome({
             assistantId: params.assistantId,
@@ -387,6 +458,19 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
             type: this.roleToType(m.role),
             content: m.content,
         }));
+        // Rebuild the same turn context appendMessageOperator would build, so the
+        // resumed run gets the scope AND the seed contexts the original run had.
+        const resumeCtx = this.buildTurnContext({
+            companyId,
+            userId,
+            userModuleIds,
+            boundContent: this.toBoundContent(contentScope ?? {}),
+        });
+        const seedContexts = await this.collectSeedContexts({
+            ctx: resumeCtx,
+            contentScope: contentScope ?? {},
+            question: "",
+        });
         let result;
         try {
             result = await this.operator.resume({
@@ -397,6 +481,9 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 userModuleIds,
                 contentId: contentScope?.contentId,
                 contentType: contentScope?.contentType,
+                scopeId: resumeCtx.scopeId,
+                scopeType: resumeCtx.scopeType,
+                seedContexts,
                 messages,
             });
         }
@@ -447,9 +534,220 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
         // pending action supersedes the (now executed) original in the response.
         return { assistantMessage: outcome.assistantMessage, action: outcome.action ?? updatedAction };
     }
+    /**
+     * List the threads bound to one resource (e.g. every assistant thread for a
+     * campaign). Delegates to the inherited `findByRelated` over the `content`
+     * relationship — the BOUND_TO traversal already exists, so there is no new
+     * Cypher here and company/owner RBAC still comes from the repository.
+     */
+    async findByBoundContent(params) {
+        const model = registry_1.modelRegistry.getByType(params.boundType);
+        if (!model) {
+            throw new common_1.BadRequestException(`Unknown resource type "${params.boundType}" for boundType.`);
+        }
+        const paginator = new jsonapi_paginator_1.JsonApiPaginator(params.query);
+        // `findByRelatedEdge`, not `findByRelated`: the latter derives the target
+        // label from `relationships.content.model`, which for this polymorphic edge
+        // is the `assistantMeta` placeholder, so it would look for
+        // `(:Assistant { id: <campaign-uuid> })` and always return nothing. This
+        // variant takes the edge spec explicitly, with the label resolved from the
+        // model registry.
+        const data = await this.repository.findByRelatedEdge({
+            cypherLabel: "BOUND_TO",
+            cypherDirection: "out",
+            relatedLabel: model.labelName,
+            relatedId: params.boundId,
+            cursor: paginator.generateCursor(),
+        });
+        return this.jsonApiService.buildList(assistant_1.AssistantDescriptor.model, data, paginator);
+    }
+    /**
+     * Build the run's UserContext once per turn. `scopeId`/`scopeType` are set
+     * only when the thread is bound to a catalogued scope ROOT (a descriptor
+     * whose compiled scope chain is empty, e.g. a campaign). A thread bound to
+     * something further down a chain still gets content scope, but not a
+     * transitive run scope — the guard has no root to confine the run to.
+     */
+    buildTurnContext(params) {
+        const ctx = {
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds: params.userModuleIds,
+        };
+        const bound = params.boundContent;
+        if (!bound?.type || !bound?.id)
+            return ctx;
+        const scope = this.graphCatalog.getEntityDetail(bound.type, params.userModuleIds)?.scope;
+        if (scope && scope.path.length === 0 && scope.rootType === bound.type) {
+            ctx.scopeId = bound.id;
+            ctx.scopeType = bound.type;
+        }
+        else {
+            this.assistantLogger.warn(`buildTurnContext: bound type "${bound.type}" is not a catalogued scope root — the turn runs unscoped.`);
+        }
+        return ctx;
+    }
+    /**
+     * Collects seed-context blocks from the app-registered providers for one
+     * turn. Help-mode turns are never seeded. A provider returning null
+     * contributes nothing; a provider that throws is logged and skipped — the
+     * turn must run (unseeded) no matter what a provider does.
+     */
+    async collectSeedContexts(params) {
+        if (!this.seedContextProviders?.length)
+            return [];
+        if (params.howToMode || params.limitToHowToId)
+            return [];
+        const collected = [];
+        for (const provider of this.seedContextProviders) {
+            try {
+                const seed = await provider.provide({
+                    companyId: params.ctx.companyId,
+                    userId: params.ctx.userId,
+                    userModuleIds: params.ctx.userModuleIds,
+                    scopeId: params.ctx.scopeId,
+                    scopeType: params.ctx.scopeType,
+                    contentId: params.contentScope.contentId,
+                    contentType: params.contentScope.contentType,
+                    question: params.question,
+                });
+                if (seed)
+                    collected.push(seed);
+            }
+            catch (err) {
+                this.assistantLogger.warn(`seed context provider failed — skipped: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return collected;
+    }
+    /**
+     * Write the `BOUND_TO` edge that scopes a thread to a resource.
+     *
+     * Deliberately NOT part of the `createFromDTO` call above: `BOUND_TO` is
+     * polymorphic, so its descriptor entry carries `assistantMeta` as a
+     * placeholder model. The generic create path reads `rel.model.labelName` to
+     * validate the target and to build the edge, so a Campaign id sent that way
+     * is looked up as `(:Assistant { id: … })` and 400s with "One or more
+     * related nodes do not exist."
+     *
+     * The label is resolved from the model registry — the same registry the
+     * descriptor's own polymorphic discriminator uses on the read path — so an
+     * unregistered type fails loudly here rather than writing a dangling edge.
+     */
+    async attachBoundContent(assistantId, boundContent) {
+        if (!boundContent)
+            return;
+        const model = registry_1.modelRegistry.getByType(boundContent.type);
+        if (!model) {
+            throw new common_1.BadRequestException(`Unknown resource type "${boundContent.type}" for the assistant's bound content.`);
+        }
+        await this.repository.bindContent({
+            assistantId,
+            targetLabel: model.labelName,
+            targetId: boundContent.id,
+        });
+    }
+    toContentScope(boundContent) {
+        return boundContent ? { contentId: boundContent.id, contentType: boundContent.type } : {};
+    }
+    toBoundContent(contentScope) {
+        return contentScope.contentId && contentScope.contentType
+            ? { type: contentScope.contentType, id: contentScope.contentId }
+            : undefined;
+    }
+    /**
+     * A BlockNote-backed field arrives as a JSON string in its own string
+     * attribute — the convention every host-app entity already uses (e.g.
+     * `Npc.description`: `JSON.stringify` out, `JSON.parse` back). Detect that
+     * shape without trusting it: a plain-text message must never be mistaken for
+     * a document, so this requires an array whose first entry is an object with
+     * a string `type`, which is the minimal shape of a BlockNote block.
+     */
+    parseBlockNoteDocument(raw) {
+        const trimmed = raw.trimStart();
+        if (!trimmed.startsWith("["))
+            return null;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!Array.isArray(parsed) || parsed.length === 0)
+                return null;
+            const first = parsed[0];
+            if (!first || typeof first !== "object" || typeof first.type !== "string")
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Derive from a user message: the markdown to persist (mention links kept, so
+     * the thread can re-render them), a plain-text form for the thread title, and
+     * the validated entity mentions to pin into the turn's focus context.
+     *
+     * Plain-text input passes straight through, so apps without a rich composer
+     * are unaffected.
+     */
+    async resolveUserTurnInput(params) {
+        const nodes = this.parseBlockNoteDocument(params.rawContent);
+        if (!nodes)
+            return { content: params.rawContent, plainText: params.rawContent, pinned: [] };
+        const content = this.blockNote.convertToMarkdown({ nodes, preserveMentions: true });
+        // Alias-only rendering: what a human reads. Used for the thread title so it
+        // does not show raw `[Name](mention://npcs/<uuid>)` markup.
+        const plainText = this.blockNote.convertToMarkdown({ nodes });
+        const pinned = await this.mentions.validate({
+            mentions: this.mentions.extract(nodes),
+            ctx: params.ctx,
+        });
+        return { content, plainText, pinned };
+    }
+    /**
+     * Materialise REFERENCES edges from the USER message to the entities that
+     * message named. The reference metadata is fixed: a mention is an explicit,
+     * maximally relevant pointer, not a ranked retrieval hit.
+     */
+    async linkPinnedMentions(params) {
+        if (!params.pinned.length)
+            return;
+        const references = params.pinned.map((mention) => ({
+            type: mention.type,
+            id: mention.id,
+            relevance: 100,
+            reason: "Named explicitly by the user in this message.",
+        }));
+        await this.assistantMessageRepo.linkReferences({ messageId: params.messageId, references });
+    }
+    /**
+     * Drop records that fall outside the run's scope root, grouping by JSON:API
+     * type so `ScopeGuard` can build one predicate per type. A no-op for an
+     * unscoped run — `ScopeGuard.filter` returns everything in that case, so the
+     * short-circuit only avoids a pointless round trip.
+     */
+    async filterByScope(records, ctx) {
+        if (!ctx.scopeId || !ctx.scopeType || records.length === 0)
+            return records;
+        const byType = new Map();
+        for (const record of records) {
+            const type = typeof record.type === "string" ? record.type : undefined;
+            const id = typeof record.id === "string" ? record.id : undefined;
+            if (!type || !id)
+                continue;
+            const bucket = byType.get(type) ?? [];
+            bucket.push(record);
+            byType.set(type, bucket);
+        }
+        const kept = new Set();
+        for (const [type, bucket] of byType) {
+            const allowed = await this.scopeGuard.filter({ type, records: bucket, ctx });
+            for (const record of allowed)
+                kept.add(record);
+        }
+        return records.filter((record) => kept.has(record));
+    }
     /**
      * Resolve the content scope from the assistant's BOUND_TO relationship if
-     * loaded. Mirrors the inline logic in `runAgentTurn`.
+     * loaded.
      */
     async resolveContentScope(assistantId) {
         try {
@@ -473,7 +771,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
             assistantId: params.assistantId,
             turnStartedAt: now.toISOString().slice(0, 19).replace(/[T:]/g, "-"),
         });
-        const hydrationContent = await this.buildHydrationMessage(params.priorMessages, params.userModuleIds);
+        const hydrationContent = await this.buildHydrationMessage(params.priorMessages, params.ctx, params.pinned);
         const trimmed = params.priorMessages.slice(-exports.MAX_MESSAGES_TO_LLM).map((m) => ({
             type: this.roleToType(m.role),
             content: m.content,
@@ -483,15 +781,25 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
             ...trimmed,
             { type: agentmessage_type_1.AgentMessageType.User, content: params.question },
         ];
+        const seedContexts = await this.collectSeedContexts({
+            ctx: params.ctx,
+            contentScope: params.contentScope,
+            question: params.question,
+            howToMode: params.howToMode,
+            limitToHowToId: params.limitToHowToId,
+        });
         return await this.operator.run({
-            companyId: params.companyId,
-            userId: params.userId,
-            userModuleIds: params.userModuleIds,
+            companyId: params.ctx.companyId,
+            userId: params.ctx.userId,
+            userModuleIds: params.ctx.userModuleIds,
             contentId: params.contentScope.contentId,
             contentType: params.contentScope.contentType,
+            scopeId: params.ctx.scopeId,
+            scopeType: params.ctx.scopeType,
             messages,
             question: params.question,
             threadId: params.threadId,
+            seedContexts,
         });
     }
     /**
@@ -604,7 +912,7 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 turnStartedAt: now.toISOString().slice(0, 19).replace(/[T:]/g, "-"),
             });
         }
-        const hydrationContent = await this.buildHydrationMessage(params.priorMessages, params.userModuleIds);
+        const hydrationContent = await this.buildHydrationMessage(params.priorMessages, params.ctx, params.pinned);
         const trimmed = params.priorMessages.slice(-exports.MAX_MESSAGES_TO_LLM).map((m) => ({
             type: this.roleToType(m.role),
             content: m.content,
@@ -614,32 +922,28 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
             ...trimmed,
             { type: agentmessage_type_1.AgentMessageType.User, content: params.newUserMessage.content },
         ];
-        // Resolve content scope from the assistant's BOUND_TO relationship if loaded.
-        let contentId;
-        let contentType;
-        if (params.assistantId) {
-            try {
-                const assistant = await this.repository.findById({ id: params.assistantId });
-                const c = assistant.content;
-                contentId = c?.id;
-                contentType = c?.type;
-            }
-            catch {
-                // If load fails, proceed without content scope.
-            }
-        }
+        const seedContexts = await this.collectSeedContexts({
+            ctx: params.ctx,
+            contentScope: params.contentScope,
+            question: params.newUserMessage.content,
+            howToMode: params.howToMode,
+            limitToHowToId: params.limitToHowToId,
+        });
         const response = await this.responder.run({
-            companyId: params.companyId,
-            userId: params.userId,
-            userModuleIds: params.userModuleIds,
-            contentId,
-            contentType,
+            companyId: params.ctx.companyId,
+            userId: params.ctx.userId,
+            userModuleIds: params.ctx.userModuleIds,
+            contentId: params.contentScope.contentId,
+            contentType: params.contentScope.contentType,
+            scopeId: params.ctx.scopeId,
+            scopeType: params.ctx.scopeType,
             dataLimits: {
                 howToMode: params.howToMode,
                 limitToHowToId: params.limitToHowToId,
             },
             messages,
             question: params.newUserMessage.content,
+            seedContexts,
         });
         return {
             id: (0, crypto_1.randomUUID)(),
@@ -673,14 +977,17 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
      * 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)
+    async buildHydrationMessage(messages, ctx, pinned = []) {
+        if (messages.length === 0 && pinned.length === 0)
             return null;
         try {
-            const pairs = await this.assistantMessageRepo.findReferencedTypeIdPairs({
-                messageIds: messages.map((m) => m.id),
-            });
-            if (pairs.length === 0)
+            const userModuleIds = ctx.userModuleIds;
+            const pairs = messages.length
+                ? await this.assistantMessageRepo.findReferencedTypeIdPairs({
+                    messageIds: messages.map((m) => m.id),
+                })
+                : [];
+            if (pairs.length === 0 && pinned.length === 0)
                 return null;
             // The most recent assistant message is the focus anchor.
             const prevAssistantId = [...messages].reverse().find((m) => m.role === "assistant")?.id;
@@ -690,6 +997,16 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
             const backgroundKeys = new Set();
             const focusRefs = [];
             const backgroundRefs = [];
+            // Entities the user named explicitly lead the focus tier: they are the
+            // subject of the new question, so they must survive FOCUS_CAP and must
+            // never be demoted to a background stub by an earlier mention.
+            for (const mention of pinned) {
+                const key = `${mention.type}/${mention.id}`;
+                if (focusKeys.has(key))
+                    continue;
+                focusKeys.add(key);
+                focusRefs.push({ type: mention.type, id: mention.id });
+            }
             for (const p of pairs) {
                 const key = `${p.type}/${p.id}`;
                 if (prevAssistantId && p.messageId === prevAssistantId) {
@@ -716,9 +1033,12 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
             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);
+            // Load focus records (full) and background records (project to label),
+            // then drop anything outside the run's scope. Hydration is a data-access
+            // point like any tool: a record from another campaign must never reach
+            // the LLM just because an earlier turn referenced it.
+            const focusRecords = await this.filterByScope(await this.loadFocusRecords(focusCapped, userModuleIds), ctx);
+            const backgroundStubs = await this.filterByScope(await this.loadBackgroundStubs(backgroundCapped, userModuleIds), ctx);
             // Diagnostic trace: in the dump it lets us see exactly which entities were
             // handed to the LLM as focus context (and whether any were bridges, since
             // bridge ids in focus are addressable directly without resolve_entity).
@@ -737,6 +1057,9 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
                 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));
+                if (pinned.length > 0) {
+                    sections.push("The user named some of these entities explicitly in the new question. Treat every entity listed above as already identified: use its id directly and do not call resolve_entity for its name.");
+                }
                 sections.push("");
             }
             if (backgroundStubs.length > 0) {
@@ -862,6 +1185,8 @@ let AssistantService = AssistantService_1 = class AssistantService extends abstr
 exports.AssistantService = AssistantService;
 exports.AssistantService = AssistantService = AssistantService_1 = __decorate([
     (0, common_1.Injectable)(),
+    __param(17, (0, common_1.Optional)()),
+    __param(17, (0, common_1.Inject)(seed_context_interface_1.ASSISTANT_SEED_CONTEXT_PROVIDERS)),
     __metadata("design:paramtypes", [jsonapi_service_1.JsonApiService,
         assistant_repository_1.AssistantRepository,
         nestjs_cls_1.ClsService,
@@ -875,6 +1200,9 @@ exports.AssistantService = AssistantService = AssistantService_1 = __decorate([
         assistant_action_service_1.AssistantActionService,
         assistant_action_repository_1.AssistantActionRepository,
         websocket_service_1.WebSocketService,
-        config_1.ConfigService])
+        config_1.ConfigService,
+        assistant_mention_extractor_1.AssistantMentionExtractor,
+        blocknote_service_1.BlockNoteService,
+        scope_guard_1.ScopeGuard, Array])
 ], AssistantService);
 //# sourceMappingURL=assistant.service.js.map