@exulu/backend 2.0.1 → 2.2.0

package/dist/{chunk-IJ4HNHOT.js → chunk-Y7JPNBFM.js}

@@ -665,6 +665,9 @@ async function tagUpdate(input) {
     budget_duration: input.budget_duration
   });
 }
+async function budgetUpdate(budget_id, patch) {
+  await call("/budget/update", { budget_id, ...patch });
+}
 async function tagDelete(name) {
   await call("/tag/delete", { name });
 }
@@ -673,8 +676,9 @@ function extractBudget(raw) {
   const max_budget = bt.max_budget ?? raw?.max_budget ?? null;
   const budget_duration = bt.budget_duration ?? raw?.budget_duration ?? null;
   const budget_reset_at = bt.budget_reset_at ?? raw?.budget_reset_at ?? null;
+  const budget_id = bt.budget_id ?? raw?.budget_id ?? null;
   const spend = typeof raw?.spend === "number" ? raw.spend : typeof bt.spend === "number" ? bt.spend : 0;
-  return { max_budget, budget_duration, budget_reset_at, spend };
+  return { max_budget, budget_duration, budget_reset_at, budget_id, spend };
 }
 async function listTags() {
   const { url, masterKey } = litellmBase();
@@ -707,7 +711,8 @@ async function listTagBudgets() {
       spend: b.spend,
       max_budget: b.max_budget,
       budget_duration: b.budget_duration,
-      budget_reset_at: b.budget_reset_at
+      budget_reset_at: b.budget_reset_at,
+      budget_id: b.budget_id
     };
   }
   const names = Object.keys(map);
@@ -753,7 +758,8 @@ async function tagInfo(names) {
       spend: b.spend,
       max_budget: b.max_budget,
       budget_duration: b.budget_duration,
-      budget_reset_at: b.budget_reset_at
+      budget_reset_at: b.budget_reset_at,
+      budget_id: b.budget_id
     };
   }
   return out;
@@ -975,7 +981,16 @@ async function setBudgetSettings(settings) {
   }).onConflict("config_key").merge({ config_value: JSON.stringify(settings) });
   return settings;
 }
-async function upsertBudget(tag, max_budget, budget_duration) {
+function parseResetAt(raw) {
+  if (raw === void 0 || raw === null || raw === "") {
+    return { valid: true, value: void 0 };
+  }
+  if (typeof raw !== "string") return { valid: false };
+  const t = Date.parse(raw);
+  if (Number.isNaN(t)) return { valid: false };
+  return { valid: true, value: new Date(t).toISOString() };
+}
+async function upsertBudget(tag, max_budget, budget_duration, budget_reset_at) {
   const info = await tagInfo([tag]);
   try {
     if (info[tag]) {
@@ -990,6 +1005,15 @@ async function upsertBudget(tag, max_budget, budget_duration) {
       await tagUpdate({ name: tag, max_budget, budget_duration });
     }
   }
+  if (budget_reset_at) {
+    const after = await tagInfo([tag]);
+    const budgetId = after[tag]?.budget_id ?? null;
+    if (budgetId) {
+      await budgetUpdate(budgetId, { budget_reset_at });
+    } else {
+      console.warn(`[EXULU] upsertBudget: no budget_id for ${tag}; reset date not applied`);
+    }
+  }
   invalidateBudgetCaches(tag);
 }
 function invalidateBudgetCaches(tag) {
@@ -1691,7 +1715,7 @@ var ExuluTool = class _ExuluTool {
       });
       providerapikey = resolved.apiKey;
     }
-    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-2PEDFZ2X.js");
+    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-M7I2TZQQ.js");
     const tools = await convertExuluToolsToAiSdkTools2(
       [this],
       [],
@@ -1774,111 +1798,8 @@ var updateStatistic = async (statistic) => {
 // src/templates/tools/convert-exulu-tools-to-ai-sdk-tools.ts
 import CryptoJS5 from "crypto-js";
 
-// src/templates/tools/project-retrieval-tool.ts
-import { z as z2 } from "zod";
-var createProjectItemsRetrievalTool = async ({
-  user,
-  role,
-  contexts,
-  projectId
-}) => {
-  let project;
-  const { db: db2 } = await postgresClient();
-  project = await db2.from("projects").where("id", projectId).first();
-  if (!project) {
-    return;
-  }
-  console.log("[EXULU] Project search tool created for project", project);
-  if (!project.project_items?.length) {
-    return;
-  }
-  const projectRetrievalTool = ExuluTool.internal({
-    id: "context_search_in_knowledge_items_added_to_project_" + projectId,
-    name: "context_search in knowledge items added to project " + project.name,
-    description: "This tool retrieves information about a project from conversations and items that were added to the project " + project.name + ".",
-    inputSchema: z2.object({
-      query: z2.string().describe("The query to retrieve information about the project " + project.name + "."),
-      keywords: z2.array(z2.string()).describe(
-        "The most relevant keywords in the query, such as names of people, companies, products, etc. in the project " + project.name + "."
-      )
-    }),
-    type: "context",
-    category: "project",
-    config: [],
-    execute: async ({ query }) => {
-      console.log("[EXULU] Project search tool searching for project", project);
-      const items = project.project_items;
-      const set = {};
-      for (const item of items) {
-        const context = item.split("/")[0];
-        if (!context) {
-          throw new Error(
-            "The item added to the project does not have a valid gid with the context id as the prefix before the first slash."
-          );
-        }
-        const id = item.split("/").slice(1).join("/");
-        if (set[context]) {
-          set[context].push(id);
-        } else {
-          set[context] = [id];
-        }
-      }
-      console.log("[EXULU] Project search tool searching through contexts", Object.keys(set));
-      const results = await Promise.all(
-        Object.keys(set).map(async (contextName) => {
-          const context = contexts.find((context2) => context2.id === contextName);
-          if (!context) {
-            console.error(
-              "[EXULU] Context not found for project information retrieval tool.",
-              contextName
-            );
-            return [];
-          }
-          const itemIds = set[contextName];
-          console.log("[EXULU] Project search tool searching through items", itemIds);
-          const result = await context.search({
-            query,
-            itemFilters: [
-              {
-                id: {
-                  in: itemIds
-                }
-              }
-            ],
-            chunkFilters: [],
-            user,
-            role,
-            method: "hybridSearch",
-            sort: {
-              field: "updatedAt",
-              direction: "desc"
-            },
-            trigger: "tool",
-            limit: 10,
-            page: 1
-          });
-          return {
-            result: result.chunks.map((chunk) => ({
-              ...chunk,
-              context: {
-                name: context.name,
-                id: context.id
-              }
-            }))
-          };
-        })
-      );
-      console.log("[EXULU] Project search tool results", results);
-      return {
-        result: JSON.stringify(results.flat())
-      };
-    }
-  });
-  return projectRetrievalTool;
-};
-
 // src/templates/tools/session-items-retrieval-tool.ts
-import { z as z3 } from "zod";
+import { z as z2 } from "zod";
 var createSessionItemsRetrievalTool = async ({
   user,
   role,
@@ -1890,8 +1811,8 @@ var createSessionItemsRetrievalTool = async ({
     id: "session_items_information_context_search",
     name: "context_search in knowledge items added to session.",
     description: "Context search in knowledge items added to session.",
-    inputSchema: z3.object({
-      query: z3.string().describe("The query to retrieve information from knowledge items added to the session.")
+    inputSchema: z2.object({
+      query: z2.string().describe("The query to retrieve information from knowledge items added to the session.")
     }),
     type: "context",
     category: "session",
@@ -1962,7 +1883,7 @@ var createSessionItemsRetrievalTool = async ({
 };
 
 // ee/agentic-retrieval/pipeline/index.ts
-import { z as z8 } from "zod";
+import { z as z7 } from "zod";
 
 // ee/entitlements.ts
 var ENTITLEMENTS = {
@@ -2106,57 +2027,57 @@ async function resolveReranker(input) {
 }
 
 // ee/agentic-retrieval/pipeline/config.ts
-import { z as z4 } from "zod";
+import { z as z3 } from "zod";
 var KB_KINDS = ["documents", "conversations", "records"];
 var DEFAULT_PREFILTER_CUTOFF = 2.5;
 var RRF_K = 60;
 var CHUNK_GROUP_MAX = 10;
-var kbProfileSchema = z4.object({
-  enabled: z4.boolean().default(true),
-  kind: z4.enum(KB_KINDS).default("documents"),
-  instructions: z4.string().default(""),
-  overrides: z4.object({
-    limit: z4.number().int().positive().optional(),
-    expand: z4.number().int().min(0).optional(),
-    multiQuery: z4.boolean().optional(),
-    hyde: z4.boolean().optional()
+var kbProfileSchema = z3.object({
+  enabled: z3.boolean().default(true),
+  kind: z3.enum(KB_KINDS).default("documents"),
+  instructions: z3.string().default(""),
+  overrides: z3.object({
+    limit: z3.number().int().positive().optional(),
+    expand: z3.number().int().min(0).optional(),
+    multiQuery: z3.boolean().optional(),
+    hyde: z3.boolean().optional()
   }).default({})
 });
-var knowledgeBasesSchema = z4.record(z4.string(), kbProfileSchema);
-var routingRuleSchema = z4.object({
-  id: z4.string(),
-  label: z4.string(),
-  description: z4.string(),
-  main: z4.array(z4.string()),
-  fallback: z4.array(z4.string()).default([])
+var knowledgeBasesSchema = z3.record(z3.string(), kbProfileSchema);
+var routingRuleSchema = z3.object({
+  id: z3.string(),
+  label: z3.string(),
+  description: z3.string(),
+  main: z3.array(z3.string()),
+  fallback: z3.array(z3.string()).default([])
 });
-var routingSchema = z4.object({ rules: z4.array(routingRuleSchema).default([]) });
-var identifierSetSchema = z4.object({
-  name: z4.string(),
-  description: z4.string().default(""),
-  examples: z4.array(z4.string()).default([]),
-  strategy: z4.enum(["fuzzy", "exact"]),
-  contexts: z4.array(z4.string()).default([])
+var routingSchema = z3.object({ rules: z3.array(routingRuleSchema).default([]) });
+var identifierSetSchema = z3.object({
+  name: z3.string(),
+  description: z3.string().default(""),
+  examples: z3.array(z3.string()).default([]),
+  strategy: z3.enum(["fuzzy", "exact"]),
+  contexts: z3.array(z3.string()).default([])
 });
-var vocabularySchema = z4.object({
-  glossary: z4.array(z4.object({ term: z4.string(), meaning: z4.string() })).default([]),
-  identifiers: z4.array(identifierSetSchema).default([]),
-  rewrites: z4.array(z4.object({ find: z4.string(), replace: z4.string() })).default([]),
-  styleHint: z4.string().default("")
+var vocabularySchema = z3.object({
+  glossary: z3.array(z3.object({ term: z3.string(), meaning: z3.string() })).default([]),
+  identifiers: z3.array(identifierSetSchema).default([]),
+  rewrites: z3.array(z3.object({ find: z3.string(), replace: z3.string() })).default([]),
+  styleHint: z3.string().default("")
 });
-var memorySchema = z4.object({
-  enabled: z4.boolean().default(true),
-  override: z4.boolean().default(false),
-  filePrioritization: z4.boolean().default(false),
-  queryAugmentation: z4.boolean().default(true)
+var memorySchema = z3.object({
+  enabled: z3.boolean().default(true),
+  override: z3.boolean().default(false),
+  filePrioritization: z3.boolean().default(false),
+  queryAugmentation: z3.boolean().default(true)
 });
-var tuningSchema = z4.object({
-  topK: z4.number().int().positive().default(5),
-  fallbackThreshold: z4.number().min(0).max(1).default(0.95),
-  pinBoost: z4.number().min(0).max(1).default(0.15),
-  identifierBoost: z4.number().min(0).max(1).default(0.15),
-  pageWindow: z4.number().int().min(0).default(1),
-  maxQueriesPerContext: z4.number().int().positive().default(5)
+var tuningSchema = z3.object({
+  topK: z3.number().int().positive().default(5),
+  fallbackThreshold: z3.number().min(0).max(1).default(0.95),
+  pinBoost: z3.number().min(0).max(1).default(0.15),
+  identifierBoost: z3.number().min(0).max(1).default(0.15),
+  pageWindow: z3.number().int().min(0).default(1),
+  maxQueriesPerContext: z3.number().int().positive().default(5)
 });
 var boolVal = (v) => v === true || v === "true" || v === 1;
 var strVal = (v, fallback) => typeof v === "string" && v.length > 0 ? v : fallback;
@@ -2212,6 +2133,7 @@ function parsePipelineConfig(raw) {
     managedContext: boolVal(r["managed_context"]),
     requirePreselectedContexts: boolVal(r["require_preselected_contexts"]),
     logging: boolVal(r["logging"]),
+    projectSearch: r["project_search"] === void 0 || 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"]),
@@ -2244,9 +2166,69 @@ function effectiveKbSettings(profile, ctx) {
   };
 }
 
+// ee/agentic-retrieval/pipeline/global-ids.ts
+function parsePreselectedItems(globalIds) {
+  const map = /* @__PURE__ */ new Map();
+  for (const gid of globalIds) {
+    const slashIdx = gid.indexOf("/");
+    if (slashIdx === -1) {
+      if (gid) map.set(gid, null);
+      continue;
+    }
+    const contextId = gid.slice(0, slashIdx);
+    const itemId = gid.slice(slashIdx + 1);
+    if (!contextId || !itemId) continue;
+    if (map.get(contextId) === null) continue;
+    const existing = map.get(contextId) ?? [];
+    existing.push(itemId);
+    map.set(contextId, existing);
+  }
+  return map;
+}
+
+// ee/agentic-retrieval/pipeline/project-scope.ts
+function resolveProjectScope(opts) {
+  const { scope, enabledContextIds, availableContextIds } = opts;
+  if (!scope || scope.items.length === 0) return void 0;
+  const itemsByContext = parsePreselectedItems(scope.items);
+  const pinsByContext = /* @__PURE__ */ new Map();
+  const scopedItemsByContext = /* @__PURE__ */ new Map();
+  const addedContextIds = [];
+  const allProjectContextIds = [];
+  for (const [ctxId, itemIds] of itemsByContext) {
+    if (!availableContextIds.has(ctxId)) {
+      console.warn(
+        `[EXULU pipeline] project "${scope.name}" references unknown context "${ctxId}" \u2014 skipping those items.`
+      );
+      continue;
+    }
+    allProjectContextIds.push(ctxId);
+    if (enabledContextIds.has(ctxId)) {
+      if (itemIds && itemIds.length > 0) pinsByContext.set(ctxId, new Set(itemIds));
+    } else {
+      scopedItemsByContext.set(ctxId, itemIds);
+      addedContextIds.push(ctxId);
+    }
+  }
+  if (allProjectContextIds.length === 0) return void 0;
+  return { pinsByContext, scopedItemsByContext, addedContextIds, allProjectContextIds };
+}
+var TRANSCRIPTIONS_CONTEXT_ID = "transcriptions";
+function buildProjectKbProfileDefaults(items) {
+  const defaults = {};
+  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;
+}
+
 // ee/agentic-retrieval/pipeline/routing.ts
 import { generateText as generateText2, Output as Output2 } from "ai";
-import { z as z6 } from "zod";
+import { z as z5 } from "zod";
 
 // src/utils/with-retry.ts
 async function withRetry(generateFn, maxRetries = 3) {
@@ -2269,7 +2251,7 @@ async function withRetry(generateFn, maxRetries = 3) {
 // ee/agentic-retrieval/pipeline/prefilter.ts
 import Fuse from "fuse.js";
 import { generateText, Output } from "ai";
-import { z as z5 } from "zod";
+import { z as z4 } from "zod";
 
 // ee/agentic-retrieval/pipeline/text-utils.ts
 var normalizeFileName = (fileName) => {
@@ -2514,9 +2496,9 @@ async function resolveIdentifierPins({
             system: set.strategy === "exact" ? EXACT_EXTRACTION_PROMPT(set) : FUZZY_EXTRACTION_PROMPT(set),
             messages: [{ role: "user", content: question }],
             output: Output.object({
-              schema: z5.object({
-                hasMatches: z5.boolean(),
-                matches: z5.array(z5.string()).optional()
+              schema: z4.object({
+                hasMatches: z4.boolean(),
+                matches: z4.array(z4.string()).optional()
               })
             }),
             maxOutputTokens: 300
@@ -2627,11 +2609,11 @@ If explicit, return the knowledge base ids. If not, return an empty array.`;
               system: buildDocPagePrompt(knownIdentifiers),
               messages: [{ role: "user", content: question }],
               output: Output2.object({
-                schema: z6.object({
-                  hasFilenameHint: z6.boolean(),
-                  filenameHints: z6.array(z6.string()).optional(),
-                  hasPageHint: z6.boolean(),
-                  pageNumber: z6.number().int().nullable().optional()
+                schema: z5.object({
+                  hasFilenameHint: z5.boolean(),
+                  filenameHints: z5.array(z5.string()).optional(),
+                  hasPageHint: z5.boolean(),
+                  pageNumber: z5.number().int().nullable().optional()
                 })
               }),
               maxOutputTokens: 300
@@ -2658,9 +2640,9 @@ If explicit, return the knowledge base ids. If not, return an empty array.`;
               temperature: 0,
               system: kbSystemPrompt,
               output: Output2.object({
-                schema: z6.object({
-                  explicitlyRequestedKnowledgeBases: z6.array(
-                    z6.enum(enabledContexts.map((c) => c.id))
+                schema: z5.object({
+                  explicitlyRequestedKnowledgeBases: z5.array(
+                    z5.enum(enabledContexts.map((c) => c.id))
                   )
                 })
               }),
@@ -2758,9 +2740,9 @@ ${extraInstructions}
             system: classifyPrompt,
             messages: [{ role: "user", content: question }],
             output: Output2.object({
-              schema: z6.object({
-                ruleId: z6.enum(ruleIds),
-                reason: z6.string()
+              schema: z5.object({
+                ruleId: z5.enum(ruleIds),
+                reason: z5.string()
               })
             }),
             maxOutputTokens: 200
@@ -2822,7 +2804,7 @@ ${extraInstructions}
 
 // ee/agentic-retrieval/pipeline/memory.ts
 import { generateText as generateText3, Output as Output3 } from "ai";
-import { z as z7 } from "zod";
+import { z as z6 } from "zod";
 
 // ee/agentic-retrieval/pipeline/multi-query.ts
 async function singleSearch({
@@ -3063,8 +3045,8 @@ async function runMemoryPhase({
             }
           ],
           output: Output3.object({
-            schema: z7.object({
-              relevantChunkIds: z7.array(z7.string()).describe(
+            schema: z6.object({
+              relevantChunkIds: z6.array(z6.string()).describe(
                 "The chunk_ids (UUIDs at the start of each bullet) of chunks containing information relevant to the user's question. Empty array if none are relevant."
               )
             })
@@ -3180,17 +3162,17 @@ ${glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n")}` : "";
               }
             ],
             output: Output3.object({
-              schema: z7.object({
-                overrides: z7.boolean().describe(
+              schema: z6.object({
+                overrides: z6.boolean().describe(
                   "True ONLY if a memory chunk directly and sufficiently answers the user's question and should be authoritative over the documents. Be strict; when unsure, false."
                 ),
-                confidence: z7.enum(["high", "medium", "low"]).describe(
+                confidence: z6.enum(["high", "medium", "low"]).describe(
                   "Confidence that the selected memory chunk(s) fully and directly answer the question."
                 ),
-                authoritativeChunkIds: z7.array(z7.string()).describe(
+                authoritativeChunkIds: z6.array(z6.string()).describe(
                   "The chunk_ids of the memory chunk(s) that directly answer the question. Empty if overrides is false."
                 ),
-                reason: z7.string().describe(
+                reason: z6.string().describe(
                   "One short sentence: why this memory does or does not directly answer the question."
                 )
               })
@@ -3221,9 +3203,9 @@ ${glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n")}` : "";
             system: "You are a helpful assistant that will strictly follow the user's instructions.",
             messages: [{ role: "user", content: PROMPT_EXTRACT_PRIORITIZED_FILES }],
             output: Output3.object({
-              schema: z7.object({
-                shouldPrioritizeFiles: z7.boolean(),
-                fileNameHints: z7.array(z7.string()).optional()
+              schema: z6.object({
+                shouldPrioritizeFiles: z6.boolean(),
+                fileNameHints: z6.array(z6.string()).optional()
               })
             }),
             maxOutputTokens: 300
@@ -3242,10 +3224,10 @@ ${glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n")}` : "";
             system: "You are a helpful assistant that will strictly follow the user's instructions.",
             messages: [{ role: "user", content: QUERY_AUGMENTATION_PROMPT }],
             output: Output3.object({
-              schema: z7.object({
-                updatedUserQuestion: z7.string(),
-                updatedRelevantKeywords: z7.array(z7.string()),
-                updatedImportantKeyword: z7.string()
+              schema: z6.object({
+                updatedUserQuestion: z6.string(),
+                updatedRelevantKeywords: z6.array(z6.string()),
+                updatedImportantKeyword: z6.string()
               })
             }),
             maxOutputTokens: 600
@@ -3426,6 +3408,7 @@ async function searchContexts(opts) {
     role,
     model,
     preselectedItems,
+    scopedItemsByContext,
     identifierPinsByContext,
     memoryPinnedItemIds,
     userPinnedItemIdsByContext,
@@ -3452,6 +3435,8 @@ async function searchContexts(opts) {
         let pinnedItemIds;
         if (hasPreselection) {
           pinnedItemIds = preselectedItems.get(ctxId) ?? [];
+        } else if (scopedItemsByContext?.has(ctxId)) {
+          pinnedItemIds = scopedItemsByContext.get(ctxId) ?? [];
         } else if (!skipPrefilter) {
           const identifierPins = identifierPinsByContext.get(ctxId) ?? /* @__PURE__ */ new Set();
           let pins = new Set(identifierPins);
@@ -3659,24 +3644,6 @@ async function rerankResults(opts) {
 }
 
 // ee/agentic-retrieval/pipeline/index.ts
-function parsePreselectedItems(globalIds) {
-  const map = /* @__PURE__ */ new Map();
-  for (const gid of globalIds) {
-    const slashIdx = gid.indexOf("/");
-    if (slashIdx === -1) {
-      if (gid) map.set(gid, null);
-      continue;
-    }
-    const contextId = gid.slice(0, slashIdx);
-    const itemId = gid.slice(slashIdx + 1);
-    if (!contextId || !itemId) continue;
-    if (map.get(contextId) === null) continue;
-    const existing = map.get(contextId) ?? [];
-    existing.push(itemId);
-    map.set(contextId, existing);
-  }
-  return map;
-}
 function addChunks(result, chunks) {
   const seen = new Set(result.chunks.map((c) => c.chunk_id));
   for (const chunk of chunks) {
@@ -3706,7 +3673,8 @@ function createAgenticRetrievalTool(opts) {
     model,
     instructions: adminInstructions,
     preselected,
-    memoryItems
+    memoryItems,
+    projectScope
   } = opts;
   const license = checkLicense();
   if (!license["agentic-retrieval"]) {
@@ -3716,7 +3684,9 @@ 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 \u2014 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 \u2014 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",
@@ -3759,10 +3729,16 @@ 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.",
@@ -3794,11 +3770,11 @@ function createAgenticRetrievalTool(opts) {
         default: '{"topK":5,"fallbackThreshold":0.95,"pinBoost":0.15,"identifierBoost":0.15,"pageWindow":1,"maxQueriesPerContext":5}'
       }
     ],
-    inputSchema: z8.object({
-      userQuery: z8.string().describe("The original unaltered question from the user"),
-      relevantKeywords: z8.array(z8.string()).describe("Keywords extracted from the user's question relevant to the search"),
-      importantKeyword: z8.string().describe("The single most important keyword from the user's question"),
-      confirmedContextIds: z8.array(z8.string()).optional().describe(
+    inputSchema: z7.object({
+      userQuery: z7.string().describe("The original unaltered question from the user"),
+      relevantKeywords: z7.array(z7.string()).describe("Keywords extracted from the user's question relevant to the search"),
+      importantKeyword: z7.string().describe("The single most important keyword from the user's question"),
+      confirmedContextIds: z7.array(z7.string()).optional().describe(
         "Knowledge base IDs explicitly confirmed by the user to be used in the retrieval. When present, only searches these contexts."
       )
     }),
@@ -3872,6 +3848,23 @@ function createAgenticRetrievalTool(opts) {
           }
         }
         const preselectedItems = parsePreselectedItems(preselected ?? []);
+        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())
+        }) : void 0;
+        if (resolvedProject) {
+          if (projectScope?.kbProfileDefaults) {
+            for (const [ctxId, profile] of Object.entries(projectScope.kbProfileDefaults)) {
+              if (!cfg.knowledgeBases[ctxId]) cfg.knowledgeBases[ctxId] = profile;
+            }
+          }
+          enabledContexts = [
+            ...enabledContexts,
+            ...resolvedProject.addedContextIds.map((id) => availableContextsById.get(id)).filter((c) => Boolean(c))
+          ];
+        }
         const contextsById = new Map(enabledContexts.map((c) => [c.id, c]));
         const kbKindById = new Map(
           enabledContexts.map((c) => [
@@ -3882,7 +3875,12 @@ function createAgenticRetrievalTool(opts) {
         const documentContexts = enabledContexts.filter(
           (c) => (cfg.knowledgeBases[c.id]?.kind ?? "documents") === "documents"
         );
-        const extraInstructions = [cfg.instructions, adminInstructions].filter(Boolean).join("\n");
+        const extraInstructions = [
+          cfg.instructions,
+          adminInstructions,
+          resolvedProject && projectScope?.customInstructions ? `Instructions for the attached project "${projectScope.name}":
+${projectScope.customInstructions}` : ""
+        ].filter(Boolean).join("\n");
         const [memResult, routResult] = await Promise.all([
           runMemoryPhase({
             memoryChunks: memoryItems ?? [],
@@ -3928,6 +3926,30 @@ function createAgenticRetrievalTool(opts) {
           yield { result: "The user has requested to search in knowledge bases that are not part of the preselected knowledge bases: " + missing.join(", ") };
           return;
         }
+        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: []
+            });
+          }
+        }
+        const fallbackContextsToSearch = fallbackContexts.filter(
+          (id) => !effectiveMainContexts.includes(id)
+        );
         const {
           updatedQuestion,
           updatedKeywords,
@@ -3954,7 +3976,7 @@ function createAgenticRetrievalTool(opts) {
         }
         const [mainSearch, speculativeFallbackSearch] = await Promise.all([
           searchContexts({
-            contextIds: mainContexts,
+            contextIds: effectiveMainContexts,
             contextsById,
             kbProfiles: cfg.knowledgeBases,
             question: updatedQuestion,
@@ -3967,13 +3989,14 @@ 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 ? searchContexts({
-            contextIds: fallbackContexts,
+          fallbackContextsToSearch.length > 0 && !hasExplicitDocAndPage ? searchContexts({
+            contextIds: fallbackContextsToSearch,
             contextsById,
             kbProfiles: cfg.knowledgeBases,
             question: updatedQuestion,
@@ -3986,6 +4009,7 @@ function createAgenticRetrievalTool(opts) {
             identifierPinsByContext,
             memoryPinnedItemIds,
             userPinnedItemIdsByContext,
+            scopedItemsByContext: resolvedProject?.scopedItemsByContext,
             rewrites: cfg.vocabulary.rewrites,
             styleHint: cfg.vocabulary.styleHint,
             maxQueries: cfg.tuning.maxQueriesPerContext,
@@ -3999,6 +4023,9 @@ function createAgenticRetrievalTool(opts) {
           })(),
           ...(function* () {
             for (const s of userPinnedItemIdsByContext.values()) yield* s;
+          })(),
+          ...(function* () {
+            if (resolvedProject) for (const s of resolvedProject.pinsByContext.values()) yield* s;
           })()
         ]);
         const userPinnedItemIds = new Set(
@@ -4066,15 +4093,15 @@ function createAgenticRetrievalTool(opts) {
           result.reasoning.push({ text: "Literal lookup satisfied; skipping fallback.", tools: [] });
           yield { result: serializeOutput(result) };
         }
-        if (!literalLookupSatisfied && fallbackContexts.length > 0 && (reranker ? mainRerank.rerank_score_max_genuine < cfg.tuning.fallbackThreshold : mainRerank.limited_results.length < cfg.tuning.topK)) {
+        if (!literalLookupSatisfied && 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({
             chunks: speculativeFallbackSearch.chunks,
@@ -4160,7 +4187,7 @@ function sanitizeToolName(name) {
 }
 
 // src/templates/tools/convert-exulu-tools-to-ai-sdk-tools.ts
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 
 // types/enums/statistics.ts
 var STATISTICS_TYPE_ENUM = {
@@ -4176,12 +4203,12 @@ var STATISTICS_TYPE_ENUM = {
 };
 
 // src/templates/tools/memory-tool.ts
-import { z as z9 } from "zod";
+import { z as z8 } from "zod";
 var createNewMemoryItemTool = (agent, context) => {
   const fields = {
-    name: z9.string().describe("The name of the item to create"),
-    description: z9.string().describe("The description of the item to create"),
-    surroundingContext: z9.string().describe("A description of the context surrounding this memory, for example if it relates to a question a user asked, a specific product, or entity etc...")
+    name: z8.string().describe("The name of the item to create"),
+    description: z8.string().describe("The description of the item to create"),
+    surroundingContext: z8.string().describe("A description of the context surrounding this memory, for example if it relates to a question a user asked, a specific product, or entity etc...")
   };
   for (const field of context.fields) {
     switch (field.type) {
@@ -4189,47 +4216,47 @@ var createNewMemoryItemTool = (agent, context) => {
       case "longText":
       case "shortText":
       case "code":
-        fields[field.name] = z9.string().describe("The " + field.name + " of the item to create");
+        fields[field.name] = z8.string().describe("The " + field.name + " of the item to create");
         break;
       case "enum":
         if (field.enumValues && field.enumValues.length > 0) {
           const enumValues = field.enumValues;
-          fields[field.name] = z9.preprocess(
+          fields[field.name] = z8.preprocess(
             (v) => typeof v === "string" ? v.toUpperCase() : v,
-            z9.enum(enumValues)
+            z8.enum(enumValues)
           ).describe(
             "The " + field.name + " of the item to create. Must be one of: " + field.enumValues.join(", ")
           );
         } else {
-          fields[field.name] = z9.string().describe("The " + field.name + " of the item to create");
+          fields[field.name] = z8.string().describe("The " + field.name + " of the item to create");
         }
         break;
       case "json":
-        fields[field.name] = z9.string({}).describe(
+        fields[field.name] = z8.string({}).describe(
           "The " + field.name + " of the item to create, it should be a valid JSON string."
         );
         break;
       case "markdown":
-        fields[field.name] = z9.string().describe(
+        fields[field.name] = z8.string().describe(
           "The " + field.name + " of the item to create, it should be a valid Markdown string."
         );
         break;
       case "number":
-        fields[field.name] = z9.number().describe("The " + field.name + " of the item to create");
+        fields[field.name] = z8.number().describe("The " + field.name + " of the item to create");
         break;
       case "boolean":
-        fields[field.name] = z9.boolean().describe("The " + field.name + " of the item to create");
+        fields[field.name] = z8.boolean().describe("The " + field.name + " of the item to create");
         break;
       case "file":
       case "uuid":
       case "date":
         break;
       default:
-        fields[field.name] = z9.string().describe("The " + field.name + " of the item to create");
+        fields[field.name] = z8.string().describe("The " + field.name + " of the item to create");
         break;
     }
   }
-  fields["visibility"] = z9.enum(["private", "public"]).optional().describe(
+  fields["visibility"] = z8.enum(["private", "public"]).optional().describe(
     "Whether this memory is private to the user or shared (public). Ask the user if unknown."
   );
   const toolName = "create_" + sanitizeName(context.name) + "_memory_item";
@@ -4239,7 +4266,7 @@ var createNewMemoryItemTool = (agent, context) => {
     category: agent.name + "_memory",
     description: "Create a new memory item in the " + agent.name + " memory context",
     type: "function",
-    inputSchema: z9.object(fields),
+    inputSchema: z8.object(fields),
     config: [],
     execute: async (params) => {
       const { name, description, surroundingContext, information, visibility, exuluConfig, user } = params;
@@ -4542,7 +4569,12 @@ function getS3Client(config) {
     credentials: {
       accessKeyId: config.fileUploads.s3key,
       secretAccessKey: config.fileUploads.s3secret
-    }
+    },
+    // AWS SDK >= 3.729 injects x-amz-checksum-crc32 (of an empty body) into
+    // presigned PUT URLs, which S3-compatible stores like MinIO reject on
+    // upload with a checksum mismatch. WHEN_REQUIRED disables that default.
+    requestChecksumCalculation: "WHEN_REQUIRED",
+    responseChecksumValidation: "WHEN_REQUIRED"
   });
   return s3Client;
 }
@@ -5424,7 +5456,7 @@ ${body}`
 // ee/invoke-skills/create-sandbox.ts
 import { createBashTool } from "bash-tool";
 import { tool as tool2 } from "ai";
-import { z as z10 } from "zod";
+import { z as z9 } from "zod";
 import CryptoJS4 from "crypto-js";
 var getAllExuluVariables = async () => {
   const { db: db2 } = await postgresClient();
@@ -5842,9 +5874,9 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   });
   const writeFileTool = tool2({
     description: 'Write content to a file in the sandbox. Creates parent directories if needed. Paths are always resolved against the session sandbox root \u2014 both relative paths ("skills/foo.md") and leading-slash paths ("/skills/foo.md") work and reach the same file. When the path is under the session artifact tree, the file is also uploaded to S3 and a short-lived presigned URL is returned in the tool output.',
-    inputSchema: z10.object({
-      path: z10.string().describe("The path where the file should be written. Relative paths and leading-slash paths are both resolved against the session sandbox root."),
-      content: z10.string().describe("The content to write to the file")
+    inputSchema: z9.object({
+      path: z9.string().describe("The path where the file should be written. Relative paths and leading-slash paths are both resolved against the session sandbox root."),
+      content: z9.string().describe("The content to write to the file")
     }),
     execute: async ({ path, content }) => {
       const resolvedPath = resolveSessionPath(path, sessionDir);
@@ -5863,8 +5895,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   });
   const readFileTool = tool2({
     description: 'Read the contents of a file from the sandbox. Paths are always resolved against the session sandbox root \u2014 both relative paths ("skills/foo.md") and leading-slash paths ("/skills/foo.md") work and reach the same file. If the file does not exist, the error message is surfaced verbatim.',
-    inputSchema: z10.object({
-      path: z10.string().describe("The path of the file to read. Relative paths and leading-slash paths are both resolved against the session sandbox root.")
+    inputSchema: z9.object({
+      path: z9.string().describe("The path of the file to read. Relative paths and leading-slash paths are both resolved against the session sandbox root.")
     }),
     execute: async ({ path }) => {
       const resolvedPath = resolveSessionPath(path, sessionDir);
@@ -5875,8 +5907,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   const originalBashTool = tools.bash;
   const bashTool = tool2({
     description: originalBashTool.description ?? "",
-    inputSchema: z10.object({
-      command: z10.string().describe("The bash command to execute.")
+    inputSchema: z9.object({
+      command: z9.string().describe("The bash command to execute.")
     }),
     execute: async (args, opts) => {
       const before = persistenceEnabled ? await snapshotSessionArtifacts() : null;
@@ -5948,9 +5980,9 @@ ${lines.join("\n")}`;
 }
 
 // src/utils/truncate-tool-output.ts
-var truncateToolOutput = (output, maxContextLength, toolName, tailFraction = 0.1) => {
+var truncateToolOutput = (output, maxContextLength, toolName, tailFraction = 0.1, charLimitOverride) => {
   const effectiveCtx = maxContextLength != null && maxContextLength > 0 ? maxContextLength : 128e3;
-  const charLimit = Math.floor(effectiveCtx * 0.25 * 4);
+  const charLimit = charLimitOverride != null && charLimitOverride > 0 ? charLimitOverride : Math.floor(effectiveCtx * 0.25 * 4);
   const clampedTail = Math.min(1, Math.max(0, tailFraction));
   if (output.length <= charLimit) return output;
   const headChars = Math.floor(charLimit * (1 - clampedTail));
@@ -5970,8 +6002,230 @@ var truncateToolOutput = (output, maxContextLength, toolName, tailFraction = 0.1
   return head + marker + tail;
 };
 
+// src/exulu/tool-output-offload.ts
+import { randomUUID as randomUUID3 } from "crypto";
+
+// src/exulu/context-budget.ts
+var DEFAULT_CONTEXT_WINDOW = 128e3;
+var deriveContextBudget = (contextWindowInput) => {
+  const contextWindow = contextWindowInput != null && contextWindowInput > 0 ? contextWindowInput : DEFAULT_CONTEXT_WINDOW;
+  const outputReserve = Math.min(32e3, Math.floor(contextWindow * 0.2));
+  const usableWindow = contextWindow - outputReserve;
+  return {
+    contextWindow,
+    outputReserve,
+    usableWindow,
+    warnThreshold: Math.floor(usableWindow * 0.8),
+    blockThreshold: Math.floor(usableWindow * 0.95),
+    toolOutputCapTokens: Math.min(25e3, Math.max(4e3, Math.floor(contextWindow * 0.1))),
+    compactionTailTokens: Math.floor(usableWindow * 0.1),
+    summaryBudgetTokens: Math.min(8e3, Math.floor(usableWindow * 0.05))
+  };
+};
+var estimateTokens = (text) => text ? Math.ceil(text.length / 4) : 0;
+var estimateMessageTokens = (message) => estimateTokens(JSON.stringify(message));
+var getCompaction = (message) => message.metadata?.compaction;
+var sliceHistoryAtCheckpoint = (messages) => {
+  let checkpointIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (getCompaction(messages[i])) {
+      checkpointIdx = i;
+      break;
+    }
+  }
+  if (checkpointIdx === -1) return messages;
+  const checkpoint = messages[checkpointIdx];
+  const coversUpTo = getCompaction(checkpoint).coversUpTo;
+  const coversIdx = messages.findIndex((m) => m.id === coversUpTo);
+  const boundary = coversIdx === -1 ? checkpointIdx : coversIdx;
+  const after = messages.filter((m, i) => i > boundary && i !== checkpointIdx);
+  return [checkpoint, ...after];
+};
+var contextOccupancy = (messages) => {
+  let anchorIdx = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    const meta = m.metadata;
+    if (getCompaction(m) || m.role === "assistant" && (typeof meta?.inputTokens === "number" || typeof meta?.lastStepInputTokens === "number")) {
+      anchorIdx = i;
+      break;
+    }
+  }
+  let total = 0;
+  let rest = messages;
+  if (anchorIdx !== -1) {
+    const anchor = messages[anchorIdx];
+    const compaction = getCompaction(anchor);
+    if (compaction) {
+      total = compaction.occupancyEstimate;
+    } else {
+      const meta = anchor.metadata;
+      total = typeof meta.lastStepInputTokens === "number" ? meta.lastStepInputTokens + (meta.lastStepOutputTokens ?? 0) : (meta.inputTokens ?? 0) + (meta.outputTokens ?? 0);
+    }
+    rest = messages.slice(anchorIdx + 1);
+  }
+  for (const m of rest) total += estimateMessageTokens(m);
+  return total;
+};
+var CONTEXT_COMPACTION_REQUIRED = "CONTEXT_COMPACTION_REQUIRED";
+var COMPACTION_INSUFFICIENT = "COMPACTION_INSUFFICIENT";
+var ContextCompactionRequiredError = class extends Error {
+  constructor(occupancy, budget) {
+    super(
+      JSON.stringify({
+        code: CONTEXT_COMPACTION_REQUIRED,
+        message: `This conversation no longer fits the model's context window (~${occupancy.toLocaleString("en-US")} of ${budget.usableWindow.toLocaleString("en-US")} usable tokens). Compact the conversation to continue.`,
+        occupancy,
+        usableWindow: budget.usableWindow,
+        contextWindow: budget.contextWindow
+      })
+    );
+    this.occupancy = occupancy;
+    this.budget = budget;
+    this.name = "ContextCompactionRequiredError";
+  }
+};
+var PROVIDER_CONTEXT_ERROR_PATTERNS = [
+  /ContextWindowExceededError/i,
+  /context.?window/i,
+  /context.?length/i,
+  /maximum context/i,
+  /prompt is too long/i,
+  /input is too long/i,
+  /token count exceeds/i,
+  /too many tokens/i
+];
+var isProviderContextLengthError = (message) => PROVIDER_CONTEXT_ERROR_PATTERNS.some((re) => re.test(message));
+var mapStreamErrorMessage = (message) => isProviderContextLengthError(message) ? JSON.stringify({
+  code: CONTEXT_COMPACTION_REQUIRED,
+  message: "The model rejected the request because the conversation exceeds its context window. Compact the conversation to continue.",
+  providerMessage: message.slice(0, 500)
+}) : message;
+
+// src/exulu/tool-output-offload.ts
+var PREVIEW_CHARS = 4e3;
+var storeAsSessionFile = async (serialized, ctx) => {
+  if (!ctx.sessionID || !ctx.exuluConfig?.fileUploads) return void 0;
+  const safeTool = ctx.toolName.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40);
+  const name = `tool-output-${safeTool}-${randomUUID3().slice(0, 8)}.txt`;
+  try {
+    await uploadFile(
+      Buffer.from(serialized, "utf-8"),
+      `sessions/${ctx.sessionID}/${name}`,
+      ctx.exuluConfig,
+      { contentType: "text/plain" },
+      ctx.user?.id
+    );
+    return name;
+  } catch (err) {
+    console.error("[EXULU] Failed to offload oversized tool output to session files.", err);
+    return void 0;
+  }
+};
+var buildNotice = (tokens, capTokens, sessionFile) => sessionFile ? `Tool output truncated: ~${tokens.toLocaleString("en-US")} tokens (limit ${capTokens.toLocaleString("en-US")}). The FULL output is saved as session file "${sessionFile}" \u2014 call read_session_file with { filename: "${sessionFile}", offset, limit } to read specific line ranges.` : `Tool output truncated: ~${tokens.toLocaleString("en-US")} tokens (limit ${capTokens.toLocaleString("en-US")}). The remainder was discarded \u2014 re-run the tool with narrower arguments.`;
+var guardToolOutput = async (value, ctx) => {
+  if (value == null) return value;
+  let serialized;
+  try {
+    serialized = typeof value === "string" ? value : JSON.stringify(value);
+  } catch {
+    return value;
+  }
+  if (typeof serialized !== "string") return value;
+  const budget = deriveContextBudget(ctx.contextWindow);
+  const tokens = estimateTokens(serialized);
+  if (tokens <= budget.toolOutputCapTokens) return value;
+  const sessionFile = await storeAsSessionFile(serialized, ctx);
+  const result = {
+    truncated: true,
+    notice: buildNotice(tokens, budget.toolOutputCapTokens, sessionFile),
+    ...sessionFile ? { sessionFile } : {},
+    preview: serialized.slice(0, PREVIEW_CHARS)
+  };
+  return result;
+};
+var guardExtractedFileText = async (filename, text, ctx) => {
+  const budget = deriveContextBudget(ctx.contextWindow);
+  const tokens = estimateTokens(text);
+  if (tokens <= budget.toolOutputCapTokens) return text;
+  const sessionFile = await storeAsSessionFile(text, { ...ctx, toolName: `upload-${filename}` });
+  const notice = sessionFile ? `[Document "${filename}" truncated: ~${tokens.toLocaleString("en-US")} tokens. The full extracted text is saved as session file "${sessionFile}" \u2014 read specific parts with read_session_file (offset/limit).]` : `[Document "${filename}" truncated: ~${tokens.toLocaleString("en-US")} tokens \u2014 the remainder is unavailable.]`;
+  return `${text.slice(0, PREVIEW_CHARS)}
+
+${notice}`;
+};
+
+// src/templates/tools/session-file-read-tool.ts
+import { z as z10 } from "zod";
+var DEFAULT_LIMIT = 250;
+var MAX_CONTENT_CHARS = 16e3;
+var createSessionFileReadTool = ({
+  sessionID,
+  user,
+  exuluConfig
+}) => {
+  if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
+  const readSessionFileExecute = async ({ filename, offset, limit }) => {
+    const safeName = String(filename ?? "").trim();
+    if (!safeName || safeName.includes("..") || safeName.includes("/") || safeName.includes("\\")) {
+      return {
+        error: "Invalid filename \u2014 pass the bare file name exactly as listed in the session files (no paths)."
+      };
+    }
+    const uploads = exuluConfig.fileUploads;
+    const generalPrefix = uploads.s3prefix ? `${uploads.s3prefix.replace(/\/$/, "")}/` : "";
+    const key = `${generalPrefix}user_${user?.id ?? "api"}/sessions/${sessionID}/${safeName}`;
+    try {
+      const url = await getPresignedUrl(uploads.s3Bucket, key, exuluConfig);
+      const res = await fetch(url);
+      if (!res.ok) {
+        return { error: `Could not read session file "${safeName}" (status ${res.status}). Check the exact file name.` };
+      }
+      const textBody = await res.text();
+      const lines = textBody.split("\n");
+      const start = (offset ?? 1) - 1;
+      const requested = limit ?? DEFAULT_LIMIT;
+      const sliced = lines.slice(start, start + requested);
+      let content = sliced.join("\n");
+      let linesReturned = sliced.length;
+      if (content.length > MAX_CONTENT_CHARS) {
+        content = content.slice(0, MAX_CONTENT_CHARS);
+        linesReturned = Math.max(1, content.split("\n").length - 1);
+        content = content + "\n[slice truncated \u2014 request fewer lines]";
+      }
+      return {
+        content,
+        totalLines: lines.length,
+        offset: start + 1,
+        linesReturned
+      };
+    } catch (err) {
+      return { error: `Failed to read session file "${safeName}": ${err instanceof Error ? err.message : "unknown error"}` };
+    }
+  };
+  return ExuluTool.internal({
+    id: "read_session_file",
+    name: "read_session_file",
+    needsApproval: false,
+    description: "Read a line range from a file stored in this session's files \u2014 including offloaded tool outputs (tool-output-*.txt) and uploaded documents. Use offset (1-based line number) and limit to page through large files instead of reading everything at once.",
+    inputSchema: z10.object({
+      filename: z10.string().describe('Exact session file name as referenced in a truncation notice, e.g. "tool-output-web_search-a1b2c3d4.txt"'),
+      offset: z10.number().int().min(1).optional().describe("1-based first line to read (default 1)"),
+      limit: z10.number().int().min(1).max(1e3).optional().describe(`Number of lines to read (default ${DEFAULT_LIMIT})`)
+    }),
+    type: "function",
+    category: "session",
+    config: [],
+    // ExuluTool's execute type is modeled on retrieval tools ({result/job/items});
+    // internal utility tools return richer shapes (memory-tool has the same
+    // mismatch). The AI SDK passes the object through verbatim, so cast.
+    execute: readSessionFileExecute
+  });
+};
+
 // src/templates/tools/convert-exulu-tools-to-ai-sdk-tools.ts
-var generateS3Key = (filename) => `${randomUUID3()}-${filename}`;
+var OUTPUT_OFFLOAD_EXEMPT_TOOL_IDS = /* @__PURE__ */ new Set(["agentic_context_search"]);
+var generateS3Key = (filename) => `${randomUUID4()}-${filename}`;
 var s3Client2;
 var getMimeType = (type) => {
   switch (type) {
@@ -6069,7 +6323,7 @@ var hydrateVariables = async (tool3) => {
   await Promise.all(promises);
   return tool3;
 };
-var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, providerapikey, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems) => {
+var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, providerapikey, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems, contextWindow, disabledTools) => {
   if (!currentTools) return {};
   if (!allExuluTools) {
     allExuluTools = [];
@@ -6077,6 +6331,8 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
   if (!contexts) {
     contexts = [];
   }
+  const budget = deriveContextBudget(contextWindow);
+  const toolOutputCharLimit = budget.toolOutputCapTokens * 4;
   let sharedSessionSandbox;
   if (sessionID && exuluConfig && agent?.sandbox_enabled === true) {
     try {
@@ -6093,16 +6349,28 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
       );
     }
   }
-  let projectRetrievalTool;
-  if (project) {
-    projectRetrievalTool = await createProjectItemsRetrievalTool({
-      user,
-      role: user?.role?.id,
-      contexts,
-      projectId: project
-    });
-    if (projectRetrievalTool) {
-      currentTools.push(projectRetrievalTool);
+  const disabled = new Set(disabledTools ?? []);
+  let projectScope;
+  if (project && !disabled.has("agentic_context_search")) {
+    const { db: db2 } = await postgresClient();
+    const projectRow = await db2.from("projects").where("id", project).first();
+    let rawItems = projectRow?.project_items;
+    if (typeof rawItems === "string") {
+      try {
+        rawItems = JSON.parse(rawItems);
+      } catch {
+        rawItems = void 0;
+      }
+    }
+    if (projectRow && Array.isArray(rawItems) && rawItems.length > 0) {
+      projectScope = {
+        id: projectRow.id,
+        name: projectRow.name,
+        description: projectRow.description ?? void 0,
+        customInstructions: projectRow.custom_instructions ?? void 0,
+        items: rawItems,
+        kbProfileDefaults: buildProjectKbProfileDefaults(rawItems)
+      };
     }
   }
   if (agent?.memory && contexts?.length) {
@@ -6113,7 +6381,7 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
       );
     }
     const createNewMemoryTool = createNewMemoryItemTool(agent, context);
-    if (createNewMemoryTool) {
+    if (createNewMemoryTool && !disabled.has(createNewMemoryTool.id)) {
       if (!currentTools) {
         currentTools = [];
       }
@@ -6128,31 +6396,62 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
       contexts,
       items: sessionItems
     });
-    if (sessionItemsRetrievalTool) {
+    if (sessionItemsRetrievalTool && !disabled.has(sessionItemsRetrievalTool.id)) {
       currentTools.push(sessionItemsRetrievalTool);
     }
   }
+  const sessionFileReadTool = createSessionFileReadTool({ sessionID, user, exuluConfig });
+  if (sessionFileReadTool && !disabled.has(sessionFileReadTool.id)) {
+    currentTools.push(sessionFileReadTool);
+  }
   console.log("[EXULU] Creating agentic search tool", contexts?.length, model);
-  if (contexts?.length && model) {
-    const agenticSearchTool = createAgenticRetrievalTool({
-      contexts: contexts.filter((context) => context.id !== agent?.memory),
-      // memory is searched by the memory phase, not as a KB
-      memoryContext: agent?.memory ? contexts.find((c) => c.id === agent.memory) : void 0,
-      user,
-      role: user?.role?.id,
-      model,
-      preselected: sessionItems,
-      memoryItems
-    });
-    if (agenticSearchTool) {
-      const index = currentTools.findIndex((tool3) => tool3.id === "agentic_context_search");
-      if (index !== -1) {
+  if (contexts?.length && model && !disabled.has("agentic_context_search")) {
+    const index = currentTools.findIndex((tool3) => tool3.id === "agentic_context_search");
+    const memoryContext = agent?.memory ? contexts.find((c) => c.id === agent.memory) : void 0;
+    if (index !== -1) {
+      const agenticSearchTool = createAgenticRetrievalTool({
+        contexts: contexts.filter((context) => context.id !== agent?.memory),
+        // memory is searched by the memory phase, not as a KB
+        memoryContext,
+        user,
+        role: user?.role?.id,
+        model,
+        preselected: sessionItems,
+        memoryItems,
+        projectScope
+      });
+      if (agenticSearchTool) {
         currentTools[index] = {
           ...currentTools[index],
           // important to keep the original tool config
           ...agenticSearchTool
         };
       }
+    } else if (projectScope) {
+      const projectContextIds = new Set(
+        projectScope.items.map((gid) => {
+          const i = gid.indexOf("/");
+          return i === -1 ? gid : gid.slice(0, i);
+        })
+      );
+      const scopedContexts = contexts.filter(
+        (c) => projectContextIds.has(c.id) && c.id !== agent?.memory
+      );
+      if (scopedContexts.length > 0) {
+        const projectSearchTool = createAgenticRetrievalTool({
+          contexts: scopedContexts,
+          memoryContext,
+          user,
+          role: user?.role?.id,
+          model,
+          preselected: [...sessionItems ?? [], ...projectScope.items],
+          memoryItems,
+          projectScope
+        });
+        if (projectSearchTool) {
+          currentTools.push(projectSearchTool);
+        }
+      }
     }
   } else {
     const agenticSearchTool = currentTools.find((tool3) => tool3.id === "agentic_context_search");
@@ -6180,7 +6479,7 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
         if (typeof result?.content === "string") {
           return {
             ...result,
-            content: truncateToolOutput(result.content, agent?.maxContextLength, "readFile", 0.05)
+            content: truncateToolOutput(result.content, budget.contextWindow, "readFile", 0.05, toolOutputCharLimit)
           };
         }
         return result;
@@ -6197,10 +6496,10 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
         return {
           ...result,
           ...typeof result?.stdout === "string" && {
-            stdout: truncateToolOutput(result.stdout, agent?.maxContextLength, "bash", 0.1)
+            stdout: truncateToolOutput(result.stdout, budget.contextWindow, "bash", 0.1, toolOutputCharLimit)
           },
           ...typeof result?.stderr === "string" && {
-            stderr: truncateToolOutput(result.stderr, agent?.maxContextLength, "bash stderr", 0.4)
+            stderr: truncateToolOutput(result.stderr, budget.contextWindow, "bash stderr", 0.4, toolOutputCharLimit)
           }
         };
       }
@@ -6336,16 +6635,30 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
               user: user?.id,
               role: user?.role?.id
             });
+            const guardCtx = {
+              toolName: cur.name,
+              contextWindow,
+              sessionID,
+              user,
+              exuluConfig
+            };
+            const offloadExempt = OUTPUT_OFFLOAD_EXEMPT_TOOL_IDS.has(cur.id);
             if (response && typeof response === "object" && Symbol.asyncIterator in response) {
               let lastValue;
               for await (const value of response) {
                 yield value;
                 lastValue = value;
               }
-              return lastValue;
+              if (offloadExempt) return lastValue;
+              const guarded = await guardToolOutput(lastValue, guardCtx);
+              if (guarded !== lastValue) {
+                yield guarded;
+              }
+              return guarded;
             } else {
-              yield response;
-              return response;
+              const guarded = offloadExempt ? response : await guardToolOutput(response, guardCtx);
+              yield guarded;
+              return guarded;
             }
           }
         }
@@ -6387,6 +6700,7 @@ export {
   listTagsByPrefix,
   getBudgetSettings,
   setBudgetSettings,
+  parseResetAt,
   upsertBudget,
   invalidateBudgetCaches,
   getTagBudgetMap,
@@ -6403,10 +6717,20 @@ export {
   OAUTH_CALLBACK_PATH,
   decryptOauthState,
   exchangeCodeForTokens,
-  createProjectItemsRetrievalTool,
   sanitizeToolName,
   reportSystemDependencies,
   downloadKeyIntoSandbox,
+  truncateToolOutput,
+  DEFAULT_CONTEXT_WINDOW,
+  deriveContextBudget,
+  estimateTokens,
+  estimateMessageTokens,
+  sliceHistoryAtCheckpoint,
+  contextOccupancy,
+  COMPACTION_INSUFFICIENT,
+  ContextCompactionRequiredError,
+  mapStreamErrorMessage,
+  guardExtractedFileText,
   hydrateVariables,
   convertExuluToolsToAiSdkTools,
   ExuluTool,