@exulu/backend 2.0.0 → 2.1.0

package/ee/agentic-retrieval/pipeline/config.test.ts

@@ -79,3 +79,18 @@ describe("effectiveKbSettings", () => {
     expect(s.kind).toBe("documents");
   });
 });
+
+describe("project_search option", () => {
+  it("defaults to true when absent or empty (empty string = backend default)", () => {
+    expect(parsePipelineConfig({}).projectSearch).toBe(true);
+    expect(parsePipelineConfig(undefined).projectSearch).toBe(true);
+    expect(parsePipelineConfig({ project_search: "" }).projectSearch).toBe(true);
+  });
+
+  it("parses explicit values", () => {
+    expect(parsePipelineConfig({ project_search: "false" }).projectSearch).toBe(false);
+    expect(parsePipelineConfig({ project_search: false }).projectSearch).toBe(false);
+    expect(parsePipelineConfig({ project_search: "true" }).projectSearch).toBe(true);
+    expect(parsePipelineConfig({ project_search: true }).projectSearch).toBe(true);
+  });
+});

package/ee/agentic-retrieval/pipeline/config.ts

@@ -69,6 +69,8 @@ export type PipelineConfig = {
   managedContext: boolean;
   requirePreselectedContexts: boolean;
   logging: boolean;
+  /** Search items attached to the chat's project as an additional source. Default true. */
+  projectSearch: boolean;
   utilityModel: string;
   knowledgeBases: Record<string, KbProfile>;
   routing: z.infer<typeof routingSchema>;
@@ -132,6 +134,10 @@ export function parsePipelineConfig(raw?: Record<string, unknown>): PipelineConf
     managedContext: boolVal(r["managed_context"]),
     requirePreselectedContexts: boolVal(r["require_preselected_contexts"]),
     logging: boolVal(r["logging"]),
+    projectSearch:
+      r["project_search"] === undefined || r["project_search"] === ""
+        ? true
+        : boolVal(r["project_search"]),
     utilityModel: strVal(r["utility_model"], ""),
     knowledgeBases: jsonVal("knowledge_bases", knowledgeBasesSchema, r["knowledge_bases"]),
     routing: jsonVal("routing", routingSchema, r["routing"]),

package/ee/agentic-retrieval/pipeline/global-ids.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse a list of global preselected IDs into a per-context map.
+ *
+ * Two supported formats:
+ *   "<context_id>/<item_id>" → specific item; value is a non-empty string[]
+ *   "<context_id>"           → full context (no item filter); value is null
+ *
+ * If both a full-context entry and specific-item entries exist for the same
+ * context, full-context (null) wins.
+ */
+export function parsePreselectedItems(globalIds: string[]): Map<string, string[] | null> {
+  const map = new Map<string, string[] | null>();
+  for (const gid of globalIds) {
+    const slashIdx = gid.indexOf("/");
+    if (slashIdx === -1) {
+      // No slash → entire context selected
+      if (gid) map.set(gid, null);
+      continue;
+    }
+    const contextId = gid.slice(0, slashIdx);
+    const itemId = gid.slice(slashIdx + 1);
+    if (!contextId || !itemId) continue;
+    // Full-context entry already wins — don't downgrade to specific items
+    if (map.get(contextId) === null) continue;
+    const existing = map.get(contextId) ?? [];
+    existing.push(itemId);
+    map.set(contextId, existing);
+  }
+  return map;
+}

package/ee/agentic-retrieval/pipeline/index.test.ts

@@ -37,7 +37,7 @@ describe("createAgenticRetrievalTool", () => {
     const names = tool.config.map((c) => c.name).sort();
     expect(names).toEqual([
       "instructions", "knowledge_bases", "logging", "managed_context", "memory",
-      "max_steps", "require_preselected_contexts", "reranker", "routing", "tuning", "utility_model", "vocabulary",
+      "max_steps", "project_search", "require_preselected_contexts", "reranker", "routing", "tuning", "utility_model", "vocabulary",
     ].sort());
     expect(tool.config.filter((c) => c.type === "json").map((c) => c.name).sort())
       .toEqual(["knowledge_bases", "memory", "routing", "tuning", "vocabulary"].sort());
@@ -138,3 +138,88 @@ describe("parsePreselectedItems", () => {
     expect(m.get("b")).toBeNull();
   });
 });
+
+describe("projectScope factory surface", () => {
+  it("declares the project_search config option with default true", () => {
+    const tool = createAgenticRetrievalTool({ contexts: [], user: undefined, role: undefined, model: undefined });
+    const entry = tool!.config.find((c: { name: string }) => c.name === "project_search");
+    expect(entry).toBeDefined();
+    expect(entry!.type).toBe("boolean");
+    expect(entry!.default).toBe(true);
+  });
+
+  it("mentions the attached project in the tool description", () => {
+    const tool = createAgenticRetrievalTool({
+      contexts: [],
+      user: undefined,
+      role: undefined,
+      model: undefined,
+      projectScope: { id: "p1", name: "Modernization", items: ["docs/i1"] },
+    });
+    expect(tool!.description).toContain('project "Modernization"');
+  });
+});
+
+describe("projectScope execute-level wiring", () => {
+  beforeEach(() => {
+    jest.requireMock("./routing").runRoutingPhase.mockClear();
+    jest.requireMock("./search").searchContexts.mockClear();
+    jest.requireMock("./rerank").rerankResults.mockClear();
+    // Restore routing default (some tests override it with mockResolvedValueOnce)
+    jest.requireMock("./routing").runRoutingPhase.mockResolvedValue({
+      mainContexts: ["docs"], fallbackContexts: [], userPinnedItemIdsByContext: new Map(),
+      userRequestedPage: null, hasExplicitDocAndPage: false, steps: [{ text: "routed" }],
+    });
+  });
+
+  it("gate-off: project_search:false suppresses project instructions, context append, and scopedItemsByContext", async () => {
+    const { runRoutingPhase } = jest.requireMock("./routing");
+    const { searchContexts } = jest.requireMock("./search");
+    const run = makeTool(
+      { project_search: false },
+      { projectScope: { id: "p1", name: "MyProject", customInstructions: "Do X", items: ["tickets/item1"] } },
+    );
+    const out = await drain(run(inputs));
+    // No "Including sources from project" step text in final output
+    const lastParsed = JSON.parse(out[out.length - 1].result);
+    expect(lastParsed.steps.every((s: any) => !s.text.includes("Including sources from project"))).toBe(true);
+    // Routing must NOT receive project custom instructions
+    const routingCall = runRoutingPhase.mock.calls[runRoutingPhase.mock.calls.length - 1][0];
+    expect(routingCall.extraInstructions ?? "").not.toContain("Instructions for the attached project");
+    // searchContexts must not receive any scopedItemsByContext entries
+    const mainSearchCall = searchContexts.mock.calls[0][0];
+    const scoped: Map<string, unknown> | undefined = mainSearchCall.scopedItemsByContext;
+    expect(scoped == null || scoped.size === 0).toBe(true);
+  });
+
+  it("case-2: enabled-context project items boost rerank pins; non-enabled context is appended and item-scoped", async () => {
+    const { searchContexts } = jest.requireMock("./search");
+    const { rerankResults } = jest.requireMock("./rerank");
+    // tickets disabled in agent config so the project adds it as a scoped source
+    const run = makeTool(
+      { knowledge_bases: { tickets: { enabled: false } } },
+      {
+        projectScope: {
+          id: "p1",
+          name: "MyProject",
+          customInstructions: "Always cite sources",
+          items: ["docs/item1", "tickets/item2"],
+        },
+      },
+    );
+    const out = await drain(run(inputs));
+    const lastParsed = JSON.parse(out[out.length - 1].result);
+    // Step announces the appended project context
+    expect(lastParsed.steps.some((s: any) => s.text.includes("Including sources from project"))).toBe(true);
+    // Main searchContexts call gets the appended context id
+    const mainSearchCall = searchContexts.mock.calls[0][0];
+    expect(mainSearchCall.contextIds).toContain("tickets");
+    // scopedItemsByContext carries the non-enabled context's item ids
+    const scoped: Map<string, string[] | null> = mainSearchCall.scopedItemsByContext;
+    expect(scoped).toBeDefined();
+    expect(scoped.get("tickets")).toEqual(["item2"]);
+    // Rerank receives pinnedItemIds that include the enabled context's project item
+    const rerankCall = rerankResults.mock.calls[0][0];
+    expect(rerankCall.state.pinnedItemIds.has("item1")).toBe(true);
+  });
+});

package/ee/agentic-retrieval/pipeline/index.ts

@@ -8,6 +8,7 @@ import { resolveReranker } from "@SRC/exulu/resolve-reranker";
 import { resolveModel } from "@SRC/exulu/resolve-model";
 import { exuluApp } from "@SRC/exulu/app/singleton";
 import { parsePipelineConfig, effectiveKbSettings } from "./config";
+import { resolveProjectScope, type ProjectScope } from "./project-scope";
 import { runRoutingPhase } from "./routing";
 import { runMemoryPhase } from "./memory";
 import { resolveIdentifierPins } from "./prefilter";
@@ -15,42 +16,8 @@ import { searchContexts } from "./search";
 import { rerankResults } from "./rerank";
 import type { AgenticRetrievalOutput, RerankState, ChunkWithScore } from "./types";
 import type { VectorSearchChunkResult } from "@SRC/graphql/resolvers/vector-search";
-
-// ---------------------------------------------------------------------------
-// parsePreselectedItems — verbatim copy of parseGlobalItemIds from v3/tools.ts
-// (renamed for the pipeline public API)
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a list of global preselected IDs into a per-context map.
- *
- * Two supported formats:
- *   "<context_id>/<item_id>" → specific item; value is a non-empty string[]
- *   "<context_id>"           → full context (no item filter); value is null
- *
- * If both a full-context entry and specific-item entries exist for the same
- * context, full-context (null) wins.
- */
-export function parsePreselectedItems(globalIds: string[]): Map<string, string[] | null> {
-  const map = new Map<string, string[] | null>();
-  for (const gid of globalIds) {
-    const slashIdx = gid.indexOf("/");
-    if (slashIdx === -1) {
-      // No slash → entire context selected
-      if (gid) map.set(gid, null);
-      continue;
-    }
-    const contextId = gid.slice(0, slashIdx);
-    const itemId = gid.slice(slashIdx + 1);
-    if (!contextId || !itemId) continue;
-    // Full-context entry already wins — don't downgrade to specific items
-    if (map.get(contextId) === null) continue;
-    const existing = map.get(contextId) ?? [];
-    existing.push(itemId);
-    map.set(contextId, existing);
-  }
-  return map;
-}
+import { parsePreselectedItems } from "./global-ids";
+export { parsePreselectedItems } from "./global-ids";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -103,6 +70,7 @@ export function createAgenticRetrievalTool(opts: {
   instructions?: string;
   preselected?: string[];
   memoryItems?: VectorSearchChunkResult[];
+  projectScope?: ProjectScope;
 }): ExuluTool | undefined {
   const {
     contexts,
@@ -113,6 +81,7 @@ export function createAgenticRetrievalTool(opts: {
     instructions: adminInstructions,
     preselected,
     memoryItems,
+    projectScope,
   } = opts;
 
   const license = checkLicense();
@@ -124,7 +93,11 @@ export function createAgenticRetrievalTool(opts: {
   return ExuluTool.internal({
     id: "agentic_context_search",
     name: "Context Search",
-    description: `Intelligent knowledge search across the available knowledge bases: ${contexts.map((c) => c.name || c.id).join(", ")}. Routes the question to the right sources, searches them with query expansion, and returns reranked passages. Results are exhaustive for the given query: do NOT repeat the call with a rephrased version of the same question — re-call only with genuinely new information (a different product or model, an explicitly named source or document, or new details from the user).`,
+    description:
+      `Intelligent knowledge search across the available knowledge bases: ${contexts.map((c) => c.name || c.id).join(", ")}. Routes the question to the right sources, searches them with query expansion, and returns reranked passages. Results are exhaustive for the given query: do NOT repeat the call with a rephrased version of the same question — re-call only with genuinely new information (a different product or model, an explicitly named source or document, or new details from the user).` +
+      // Note: the description suffix intentionally remains even when the per-agent project_search
+      // config is off — the config is only known at execute time, not at factory time.
+      (projectScope ? ` Also searches the knowledge items attached to the project "${projectScope.name}".` : ""),
     category: "contexts",
     needsApproval: false,
     type: "context",
@@ -167,10 +140,17 @@ export function createAgenticRetrievalTool(opts: {
       },
       {
         name: "max_steps",
-        description: "Maximum reasoning/tool steps the CALLING agent may take on a message while this tool is enabled (bounds retry loops and token cost). 0 = platform default (5, or 10 with skills).",
+        description: "Maximum knowledge searches the agent may run for one message. Once spent, the search tool is disabled for the rest of the turn. 0 = no search-specific cap (the agent's overall tool-step budget still applies).",
         type: "number",
         default: 0,
       },
+      {
+        name: "project_search",
+        description:
+          "Automatically include items attached to the chat's project as an additional knowledge source (boosts them in shared sources, adds scoped search for others).",
+        type: "boolean",
+        default: true,
+      },
       {
         name: "knowledge_bases",
         description: "Per-knowledge-base profiles: enabled, kind (documents | conversations | records), instructions, and per-KB overrides (limit, expand, multiQuery, hyde). JSON object keyed by context id.",
@@ -309,6 +289,33 @@ export function createAgenticRetrievalTool(opts: {
       // ── Preselected items map ─────────────────────────────────────────────
       const preselectedItems = parsePreselectedItems(preselected ?? []);
 
+      // ── Project scope: additional source, never narrows configured sources ──
+      const availableContextsById = new Map(contexts.map((c) => [c.id, c]));
+      const resolvedProject = cfg.projectSearch
+        ? resolveProjectScope({
+            scope: projectScope,
+            enabledContextIds: new Set(enabledContexts.map((c) => c.id)),
+            availableContextIds: new Set(availableContextsById.keys()),
+          })
+        : undefined;
+      if (resolvedProject) {
+        // Synthesized profile defaults (e.g. transcriptions → conversations kind);
+        // a stored knowledge_bases profile always wins.
+        if (projectScope?.kbProfileDefaults) {
+          for (const [ctxId, profile] of Object.entries(projectScope.kbProfileDefaults)) {
+            if (!cfg.knowledgeBases[ctxId]) cfg.knowledgeBases[ctxId] = profile;
+          }
+        }
+        // Copy-on-write: enabledContexts may alias the factory's contexts array
+        // (the restore-all branch above), so never push into it.
+        enabledContexts = [
+          ...enabledContexts,
+          ...resolvedProject.addedContextIds
+            .map((id) => availableContextsById.get(id))
+            .filter((c): c is NonNullable<typeof c> => Boolean(c)),
+        ];
+      }
+
       // ── Derived maps ──────────────────────────────────────────────────────
       const contextsById = new Map(enabledContexts.map((c) => [c.id, c]));
       const kbKindById = new Map(
@@ -322,7 +329,15 @@ export function createAgenticRetrievalTool(opts: {
       );
 
       // ── Phase 1: memory + routing in parallel ─────────────────────────────
-      const extraInstructions = [cfg.instructions, adminInstructions]
+      // Gate on resolvedProject: when project_search is off, resolvedProject is undefined
+      // and project custom instructions must NOT leak into routing/HyDE.
+      const extraInstructions = [
+        cfg.instructions,
+        adminInstructions,
+        resolvedProject && projectScope?.customInstructions
+          ? `Instructions for the attached project "${projectScope.name}":\n${projectScope.customInstructions}`
+          : "",
+      ]
         .filter(Boolean)
         .join("\n");
 
@@ -377,6 +392,36 @@ export function createAgenticRetrievalTool(opts: {
         return;
       }
 
+      // ── Project sources are always-main (attaching a project is an explicit signal) ──
+      let effectiveMainContexts = mainContexts;
+      if (resolvedProject) {
+        const mainSet = new Set(mainContexts);
+        const appended = resolvedProject.allProjectContextIds.filter(
+          (id) => !mainSet.has(id) && contextsById.has(id),
+        );
+        if (appended.length > 0) {
+          effectiveMainContexts = [...mainContexts, ...appended];
+          result.steps.push({
+            stepNumber: 1,
+            text: `Including sources from project "${projectScope!.name}": ${appended.join(", ")}`,
+            toolCalls: [],
+            chunks: [],
+            tokens: 0,
+          });
+          result.reasoning.push({
+            text: `Including project sources: ${appended.join(", ")}`,
+            tools: [],
+          });
+        }
+      }
+
+      // A project context appended to effectiveMainContexts can also appear in fallbackContexts
+      // (routing classified it as enabled before the project append). Deduplicate to avoid
+      // double-searching the same context in the speculative fallback pass.
+      const fallbackContextsToSearch = fallbackContexts.filter(
+        (id) => !effectiveMainContexts.includes(id),
+      );
+
       const {
         updatedQuestion,
         updatedKeywords,
@@ -409,7 +454,7 @@ export function createAgenticRetrievalTool(opts: {
       // ── Phase 2: main + speculative fallback searchContexts in parallel ───
       const [mainSearch, speculativeFallbackSearch] = await Promise.all([
         searchContexts({
-          contextIds: mainContexts,
+          contextIds: effectiveMainContexts,
           contextsById,
           kbProfiles: cfg.knowledgeBases,
           question: updatedQuestion,
@@ -422,14 +467,15 @@ export function createAgenticRetrievalTool(opts: {
           identifierPinsByContext,
           memoryPinnedItemIds,
           userPinnedItemIdsByContext,
+          scopedItemsByContext: resolvedProject?.scopedItemsByContext,
           rewrites: cfg.vocabulary.rewrites,
           styleHint: cfg.vocabulary.styleHint,
           maxQueries: cfg.tuning.maxQueriesPerContext,
           skipPrefilter: false,
         }),
-        fallbackContexts.length > 0 && !hasExplicitDocAndPage
+        fallbackContextsToSearch.length > 0 && !hasExplicitDocAndPage
           ? searchContexts({
-              contextIds: fallbackContexts,
+              contextIds: fallbackContextsToSearch,
               contextsById,
               kbProfiles: cfg.knowledgeBases,
               question: updatedQuestion,
@@ -442,6 +488,7 @@ export function createAgenticRetrievalTool(opts: {
               identifierPinsByContext,
               memoryPinnedItemIds,
               userPinnedItemIdsByContext,
+              scopedItemsByContext: resolvedProject?.scopedItemsByContext,
               rewrites: cfg.vocabulary.rewrites,
               styleHint: cfg.vocabulary.styleHint,
               maxQueries: cfg.tuning.maxQueriesPerContext,
@@ -451,7 +498,7 @@ export function createAgenticRetrievalTool(opts: {
       ]);
 
       // ── Build rerank state ────────────────────────────────────────────────
-      // pinnedItemIds = memory ∪ exact identifier pins ∪ user pins
+      // pinnedItemIds = memory ∪ exact identifier pins ∪ user pins ∪ project pins
       const pinnedItemIds = new Set<string>([
         ...memoryPinnedItemIds,
         ...(function* () {
@@ -460,6 +507,9 @@ export function createAgenticRetrievalTool(opts: {
         ...(function* () {
           for (const s of userPinnedItemIdsByContext.values()) yield* s;
         })(),
+        ...(function* () {
+          if (resolvedProject) for (const s of resolvedProject.pinsByContext.values()) yield* s;
+        })(),
       ]);
       // userPinnedItemIds = user pins only
       const userPinnedItemIds = new Set<string>(
@@ -548,19 +598,19 @@ export function createAgenticRetrievalTool(opts: {
       // ── Fallback gate ─────────────────────────────────────────────────────
       if (
         !literalLookupSatisfied &&
-        fallbackContexts.length > 0 &&
+        fallbackContextsToSearch.length > 0 &&
         (reranker
           ? mainRerank.rerank_score_max_genuine < cfg.tuning.fallbackThreshold
           : mainRerank.limited_results.length < cfg.tuning.topK)
       ) {
         result.steps.push({
           stepNumber: 1,
-          text: `Using fallback search in ${fallbackContexts.join(", ")}`,
+          text: `Using fallback search in ${fallbackContextsToSearch.join(", ")}`,
           toolCalls: [],
           chunks: [],
           tokens: 0,
         });
-        result.reasoning.push({ text: `Fallback search in ${fallbackContexts.join(", ")}`, tools: [] });
+        result.reasoning.push({ text: `Fallback search in ${fallbackContextsToSearch.join(", ")}`, tools: [] });
         yield { result: serializeOutput(result) };
 
         const fallbackRerank = await rerankResults({

package/ee/agentic-retrieval/pipeline/project-scope.test.ts

@@ -0,0 +1,73 @@
+import { resolveProjectScope, buildProjectKbProfileDefaults } from "./project-scope";
+
+const baseScope = {
+  id: "p1",
+  name: "Elevator Modernization",
+  items: ["docs/item-1", "docs/item-2", "tickets/item-9", "wiki"],
+};
+
+describe("resolveProjectScope", () => {
+  it("returns undefined for no scope or empty items", () => {
+    expect(resolveProjectScope({ scope: undefined, enabledContextIds: new Set(), availableContextIds: new Set() })).toBeUndefined();
+    expect(resolveProjectScope({ scope: { ...baseScope, items: [] }, enabledContextIds: new Set(), availableContextIds: new Set(["docs"]) })).toBeUndefined();
+  });
+
+  it("enabled contexts get PINS (boost), never filters", () => {
+    const r = resolveProjectScope({
+      scope: baseScope,
+      enabledContextIds: new Set(["docs", "tickets", "wiki"]),
+      availableContextIds: new Set(["docs", "tickets", "wiki"]),
+    })!;
+    expect(r.pinsByContext.get("docs")).toEqual(new Set(["item-1", "item-2"]));
+    expect(r.pinsByContext.get("tickets")).toEqual(new Set(["item-9"]));
+    expect(r.scopedItemsByContext.size).toBe(0);
+    expect(r.addedContextIds).toEqual([]);
+    // bare-context "wiki" is already enabled in full → no pin entry either
+    expect(r.pinsByContext.has("wiki")).toBe(false);
+    expect(new Set(r.allProjectContextIds)).toEqual(new Set(["docs", "tickets", "wiki"]));
+  });
+
+  it("non-enabled contexts get added item-scoped; bare-context entry scopes to whole context (null)", () => {
+    const r = resolveProjectScope({
+      scope: baseScope,
+      enabledContextIds: new Set(["docs"]),
+      availableContextIds: new Set(["docs", "tickets", "wiki"]),
+    })!;
+    expect(r.pinsByContext.get("docs")).toEqual(new Set(["item-1", "item-2"]));
+    expect(r.scopedItemsByContext.get("tickets")).toEqual(["item-9"]);
+    expect(r.scopedItemsByContext.get("wiki")).toBeNull();
+    expect(new Set(r.addedContextIds)).toEqual(new Set(["tickets", "wiki"]));
+  });
+
+  it("unknown contexts are dropped with a warning, not an error", () => {
+    const r = resolveProjectScope({
+      scope: { ...baseScope, items: ["ghost/item-1", "docs/item-1"] },
+      enabledContextIds: new Set(["docs"]),
+      availableContextIds: new Set(["docs"]),
+    })!;
+    expect(r.allProjectContextIds).toEqual(["docs"]);
+    expect(r.pinsByContext.get("docs")).toEqual(new Set(["item-1"]));
+  });
+
+  it("returns undefined when every referenced context is unknown", () => {
+    expect(
+      resolveProjectScope({
+        scope: { ...baseScope, items: ["ghost/x"] },
+        enabledContextIds: new Set(),
+        availableContextIds: new Set(["docs"]),
+      }),
+    ).toBeUndefined();
+  });
+});
+
+describe("buildProjectKbProfileDefaults", () => {
+  it("maps the transcriptions context to conversations kind", () => {
+    expect(buildProjectKbProfileDefaults(["transcriptions/t1", "docs/d1"])).toEqual({
+      transcriptions: { enabled: true, kind: "conversations", instructions: "", overrides: {} },
+    });
+  });
+
+  it("returns {} when transcriptions is not referenced", () => {
+    expect(buildProjectKbProfileDefaults(["docs/d1", "wiki"])).toEqual({});
+  });
+});

package/ee/agentic-retrieval/pipeline/project-scope.ts

@@ -0,0 +1,77 @@
+import type { KbProfile } from "./config";
+import { parsePreselectedItems } from "./global-ids";
+
+/** Identity + items of the project attached to the current chat session. */
+export type ProjectScope = {
+  id: string;
+  name: string;
+  description?: string;
+  customInstructions?: string;
+  /** Raw project_items gids: "<contextId>/<itemId>" or bare "<contextId>" (= whole context). */
+  items: string[];
+  /** Synthesized per-context profile defaults; a stored knowledge_bases profile always wins. */
+  kbProfileDefaults?: Record<string, KbProfile>;
+};
+
+export type ResolvedProjectScope = {
+  /** Contexts the instance already searches in full: project items only BOOST reranking. */
+  pinsByContext: Map<string, Set<string>>;
+  /** Contexts added for the project: hard item filter (null = whole context). */
+  scopedItemsByContext: Map<string, string[] | null>;
+  addedContextIds: string[];
+  allProjectContextIds: string[];
+};
+
+/**
+ * Split a project's items into pin vs scoped-source treatment. The invariant:
+ * a project may ADD scope but must never NARROW what the agent already searches.
+ */
+export function resolveProjectScope(opts: {
+  scope: ProjectScope | undefined;
+  enabledContextIds: Set<string>;
+  availableContextIds: Set<string>;
+}): ResolvedProjectScope | undefined {
+  const { scope, enabledContextIds, availableContextIds } = opts;
+  if (!scope || scope.items.length === 0) return undefined;
+
+  const itemsByContext = parsePreselectedItems(scope.items);
+  const pinsByContext = new Map<string, Set<string>>();
+  const scopedItemsByContext = new Map<string, string[] | null>();
+  const addedContextIds: string[] = [];
+  const allProjectContextIds: string[] = [];
+
+  for (const [ctxId, itemIds] of itemsByContext) {
+    if (!availableContextIds.has(ctxId)) {
+      console.warn(
+        `[EXULU pipeline] project "${scope.name}" references unknown context "${ctxId}" — skipping those items.`,
+      );
+      continue;
+    }
+    allProjectContextIds.push(ctxId);
+    if (enabledContextIds.has(ctxId)) {
+      if (itemIds && itemIds.length > 0) pinsByContext.set(ctxId, new Set(itemIds));
+      // bare-context entry on an already-enabled context adds nothing
+    } else {
+      scopedItemsByContext.set(ctxId, itemIds);
+      addedContextIds.push(ctxId);
+    }
+  }
+
+  if (allProjectContextIds.length === 0) return undefined;
+  return { pinsByContext, scopedItemsByContext, addedContextIds, allProjectContextIds };
+}
+
+const TRANSCRIPTIONS_CONTEXT_ID = "transcriptions";
+
+/** Kind heuristic for auto-configured project sources (design spec §7.3). */
+export function buildProjectKbProfileDefaults(items: string[]): Record<string, KbProfile> {
+  const defaults: Record<string, KbProfile> = {};
+  for (const gid of items) {
+    const slashIdx = gid.indexOf("/");
+    const ctxId = slashIdx === -1 ? gid : gid.slice(0, slashIdx);
+    if (ctxId === TRANSCRIPTIONS_CONTEXT_ID && !defaults[ctxId]) {
+      defaults[ctxId] = { enabled: true, kind: "conversations", instructions: "", overrides: {} };
+    }
+  }
+  return defaults;
+}

package/ee/agentic-retrieval/pipeline/search.test.ts

@@ -146,4 +146,31 @@ describe("searchContexts", () => {
     const call = (multiQuerySearch as jest.Mock).mock.calls[0][0];
     expect(call.queries).not.toContain("HYDE PASSAGE");
   });
+
+  it("project-scoped contexts hard-filter to the project's items", async () => {
+    await searchContexts({
+      ...base, contextIds: ["docs"],
+      scopedItemsByContext: new Map([["docs", ["pj1", "pj2"]]]),
+      identifierPinsByContext: new Map([["docs", new Set(["i1"])]]),
+    });
+    expect((multiQuerySearch as jest.Mock).mock.calls[0][0].pinnedItemIds).toEqual(["pj1", "pj2"]);
+  });
+
+  it("project-scoped whole-context entry (null) searches the context unfiltered", async () => {
+    await searchContexts({
+      ...base, contextIds: ["docs"],
+      scopedItemsByContext: new Map([["docs", null]]),
+      identifierPinsByContext: new Map([["docs", new Set(["i1"])]]),
+    });
+    expect((multiQuerySearch as jest.Mock).mock.calls[0][0].pinnedItemIds).toEqual([]);
+  });
+
+  it("session preselection wins over project scoping", async () => {
+    await searchContexts({
+      ...base, contextIds: ["docs"],
+      preselectedItems: new Map([["docs", ["s1"]]]),
+      scopedItemsByContext: new Map([["docs", ["pj1"]]]),
+    });
+    expect((multiQuerySearch as jest.Mock).mock.calls[0][0].pinnedItemIds).toEqual(["s1"]);
+  });
 });

package/ee/agentic-retrieval/pipeline/search.ts

@@ -23,6 +23,7 @@ export async function searchContexts(opts: {
   role: any;
   model: any;
   preselectedItems: Map<string, string[] | null>;
+  scopedItemsByContext?: Map<string, string[] | null>;  // Project-added sources: hard item filter per context (null = whole context).
   identifierPinsByContext: Map<string, Set<string>>;   // from resolveIdentifierPins
   memoryPinnedItemIds: Set<string>;                     // from memory phase (documents kind only)
   userPinnedItemIdsByContext: Map<string, Set<string>>; // from routing phase
@@ -42,6 +43,7 @@ export async function searchContexts(opts: {
     role,
     model,
     preselectedItems,
+    scopedItemsByContext,
     identifierPinsByContext,
     memoryPinnedItemIds,
     userPinnedItemIdsByContext,
@@ -80,6 +82,11 @@ export async function searchContexts(opts: {
         if (hasPreselection) {
           // null value = whole context = no filter = []
           pinnedItemIds = preselectedItems.get(ctxId) ?? [];
+        } else if (scopedItemsByContext?.has(ctxId)) {
+          // Project-scoped source: restrict to the project's items for this
+          // context (null = whole context). Deliberately NOT unioned with
+          // identifier/memory pins — those would widen a scoped source.
+          pinnedItemIds = scopedItemsByContext.get(ctxId) ?? [];
         } else if (!skipPrefilter) {
           // Rule 2: No preselection and !skipPrefilter
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exulu/backend",
   "author": "Qventu Bv.",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "main": "./dist/index.js",
   "private": false,
   "publishConfig": {