@exulu/backend 2.0.1 → 2.1.0

package/dist/index.cjs

@@ -2875,126 +2875,14 @@ var init_wrap_execute = __esm({
   }
 });
 
-// src/templates/tools/project-retrieval-tool.ts
-var import_zod2, createProjectItemsRetrievalTool;
-var init_project_retrieval_tool = __esm({
-  "src/templates/tools/project-retrieval-tool.ts"() {
-    "use strict";
-    init_cjs_shims();
-    init_tool();
-    import_zod2 = require("zod");
-    init_client();
-    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: import_zod2.z.object({
-          query: import_zod2.z.string().describe("The query to retrieve information about the project " + project.name + "."),
-          keywords: import_zod2.z.array(import_zod2.z.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
-var import_zod3, createSessionItemsRetrievalTool;
+var import_zod2, createSessionItemsRetrievalTool;
 var init_session_items_retrieval_tool = __esm({
   "src/templates/tools/session-items-retrieval-tool.ts"() {
     "use strict";
     init_cjs_shims();
     init_tool();
-    import_zod3 = require("zod");
+    import_zod2 = require("zod");
     createSessionItemsRetrievalTool = async ({
       user,
       role,
@@ -3006,8 +2894,8 @@ var init_session_items_retrieval_tool = __esm({
         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: import_zod3.z.object({
-          query: import_zod3.z.string().describe("The query to retrieve information from knowledge items added to the session.")
+        inputSchema: import_zod2.z.object({
+          query: import_zod2.z.string().describe("The query to retrieve information from knowledge items added to the session.")
         }),
         type: "context",
         category: "session",
@@ -3079,6 +2967,80 @@ var init_session_items_retrieval_tool = __esm({
   }
 });
 
+// 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;
+}
+var init_global_ids = __esm({
+  "ee/agentic-retrieval/pipeline/global-ids.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
+// 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 };
+}
+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;
+}
+var TRANSCRIPTIONS_CONTEXT_ID;
+var init_project_scope = __esm({
+  "ee/agentic-retrieval/pipeline/project-scope.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_global_ids();
+    TRANSCRIPTIONS_CONTEXT_ID = "transcriptions";
+  }
+});
+
 // src/utils/sanitize-tool-name.ts
 function sanitizeToolName(name) {
   if (typeof name !== "string") return "";
@@ -3106,19 +3068,19 @@ var init_sanitize_tool_name = __esm({
 });
 
 // src/templates/tools/memory-tool.ts
-var import_zod4, createNewMemoryItemTool;
+var import_zod3, createNewMemoryItemTool;
 var init_memory_tool = __esm({
   "src/templates/tools/memory-tool.ts"() {
     "use strict";
     init_cjs_shims();
     init_tool();
-    import_zod4 = require("zod");
+    import_zod3 = require("zod");
     init_sanitize_name();
     createNewMemoryItemTool = (agent, context) => {
       const fields = {
-        name: import_zod4.z.string().describe("The name of the item to create"),
-        description: import_zod4.z.string().describe("The description of the item to create"),
-        surroundingContext: import_zod4.z.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: import_zod3.z.string().describe("The name of the item to create"),
+        description: import_zod3.z.string().describe("The description of the item to create"),
+        surroundingContext: import_zod3.z.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) {
@@ -3126,47 +3088,47 @@ var init_memory_tool = __esm({
           case "longText":
           case "shortText":
           case "code":
-            fields[field.name] = import_zod4.z.string().describe("The " + field.name + " of the item to create");
+            fields[field.name] = import_zod3.z.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] = import_zod4.z.preprocess(
+              fields[field.name] = import_zod3.z.preprocess(
                 (v) => typeof v === "string" ? v.toUpperCase() : v,
-                import_zod4.z.enum(enumValues)
+                import_zod3.z.enum(enumValues)
               ).describe(
                 "The " + field.name + " of the item to create. Must be one of: " + field.enumValues.join(", ")
               );
             } else {
-              fields[field.name] = import_zod4.z.string().describe("The " + field.name + " of the item to create");
+              fields[field.name] = import_zod3.z.string().describe("The " + field.name + " of the item to create");
             }
             break;
           case "json":
-            fields[field.name] = import_zod4.z.string({}).describe(
+            fields[field.name] = import_zod3.z.string({}).describe(
               "The " + field.name + " of the item to create, it should be a valid JSON string."
             );
             break;
           case "markdown":
-            fields[field.name] = import_zod4.z.string().describe(
+            fields[field.name] = import_zod3.z.string().describe(
               "The " + field.name + " of the item to create, it should be a valid Markdown string."
             );
             break;
           case "number":
-            fields[field.name] = import_zod4.z.number().describe("The " + field.name + " of the item to create");
+            fields[field.name] = import_zod3.z.number().describe("The " + field.name + " of the item to create");
             break;
           case "boolean":
-            fields[field.name] = import_zod4.z.boolean().describe("The " + field.name + " of the item to create");
+            fields[field.name] = import_zod3.z.boolean().describe("The " + field.name + " of the item to create");
             break;
           case "file":
           case "uuid":
           case "date":
             break;
           default:
-            fields[field.name] = import_zod4.z.string().describe("The " + field.name + " of the item to create");
+            fields[field.name] = import_zod3.z.string().describe("The " + field.name + " of the item to create");
             break;
         }
       }
-      fields["visibility"] = import_zod4.z.enum(["private", "public"]).optional().describe(
+      fields["visibility"] = import_zod3.z.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";
@@ -3176,7 +3138,7 @@ var init_memory_tool = __esm({
         category: agent.name + "_memory",
         description: "Create a new memory item in the " + agent.name + " memory context",
         type: "function",
-        inputSchema: import_zod4.z.object(fields),
+        inputSchema: import_zod3.z.object(fields),
         config: [],
         execute: async (params) => {
           const { name, description, surroundingContext, information, visibility, exuluConfig, user } = params;
@@ -3747,9 +3709,9 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   });
   const writeFileTool = (0, import_ai2.tool)({
     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: import_zod5.z.object({
-      path: import_zod5.z.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: import_zod5.z.string().describe("The content to write to the file")
+    inputSchema: import_zod4.z.object({
+      path: import_zod4.z.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: import_zod4.z.string().describe("The content to write to the file")
     }),
     execute: async ({ path: path2, content }) => {
       const resolvedPath = resolveSessionPath(path2, sessionDir);
@@ -3768,8 +3730,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   });
   const readFileTool = (0, import_ai2.tool)({
     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: import_zod5.z.object({
-      path: import_zod5.z.string().describe("The path of the file to read. Relative paths and leading-slash paths are both resolved against the session sandbox root.")
+    inputSchema: import_zod4.z.object({
+      path: import_zod4.z.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: path2 }) => {
       const resolvedPath = resolveSessionPath(path2, sessionDir);
@@ -3780,8 +3742,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   const originalBashTool = tools.bash;
   const bashTool = (0, import_ai2.tool)({
     description: originalBashTool.description ?? "",
-    inputSchema: import_zod5.z.object({
-      command: import_zod5.z.string().describe("The bash command to execute.")
+    inputSchema: import_zod4.z.object({
+      command: import_zod4.z.string().describe("The bash command to execute.")
     }),
     execute: async (args, opts) => {
       const before = persistenceEnabled ? await snapshotSessionArtifacts() : null;
@@ -3851,7 +3813,7 @@ ${lines.join("\n")}`;
   sandboxCache.set(sessionId, { handle, installedSkills });
   return handle;
 }
-var import_sandbox_runtime, import_promises, import_node_fs5, import_node_path4, import_node_child_process3, import_node_util2, import_bash_tool, import_ai2, import_zod5, import_crypto_js4, getAllExuluVariables, execAsync2, EXEC_MAX_BUFFER, sandboxProbePromise, SANDBOX_FALLBACK_INSTRUCTIONS, degradedModeLogged, sandboxCache;
+var import_sandbox_runtime, import_promises, import_node_fs5, import_node_path4, import_node_child_process3, import_node_util2, import_bash_tool, import_ai2, import_zod4, import_crypto_js4, getAllExuluVariables, execAsync2, EXEC_MAX_BUFFER, sandboxProbePromise, SANDBOX_FALLBACK_INSTRUCTIONS, degradedModeLogged, sandboxCache;
 var init_create_sandbox = __esm({
   "ee/invoke-skills/create-sandbox.ts"() {
     "use strict";
@@ -3866,7 +3828,7 @@ var init_create_sandbox = __esm({
     init_system_dependencies();
     import_bash_tool = require("bash-tool");
     import_ai2 = require("ai");
-    import_zod5 = require("zod");
+    import_zod4 = require("zod");
     init_variable();
     import_crypto_js4 = __toESM(require("crypto-js"), 1);
     init_client();
@@ -3910,9 +3872,9 @@ var init_truncate_tool_output = __esm({
   "src/utils/truncate-tool-output.ts"() {
     "use strict";
     init_cjs_shims();
-    truncateToolOutput = (output, maxContextLength, toolName, tailFraction = 0.1) => {
+    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));
@@ -3934,13 +3896,257 @@ var init_truncate_tool_output = __esm({
   }
 });
 
+// src/exulu/context-budget.ts
+var DEFAULT_CONTEXT_WINDOW, deriveContextBudget, estimateTokens, estimateMessageTokens, getCompaction, sliceHistoryAtCheckpoint, contextOccupancy, CONTEXT_COMPACTION_REQUIRED, COMPACTION_INSUFFICIENT, ContextCompactionRequiredError, PROVIDER_CONTEXT_ERROR_PATTERNS, isProviderContextLengthError, mapStreamErrorMessage;
+var init_context_budget = __esm({
+  "src/exulu/context-budget.ts"() {
+    "use strict";
+    init_cjs_shims();
+    DEFAULT_CONTEXT_WINDOW = 128e3;
+    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))
+      };
+    };
+    estimateTokens = (text) => text ? Math.ceil(text.length / 4) : 0;
+    estimateMessageTokens = (message) => estimateTokens(JSON.stringify(message));
+    getCompaction = (message) => message.metadata?.compaction;
+    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];
+    };
+    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;
+    };
+    CONTEXT_COMPACTION_REQUIRED = "CONTEXT_COMPACTION_REQUIRED";
+    COMPACTION_INSUFFICIENT = "COMPACTION_INSUFFICIENT";
+    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";
+      }
+    };
+    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
+    ];
+    isProviderContextLengthError = (message) => PROVIDER_CONTEXT_ERROR_PATTERNS.some((re) => re.test(message));
+    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 import_node_crypto3, PREVIEW_CHARS, storeAsSessionFile, buildNotice, guardToolOutput, guardExtractedFileText;
+var init_tool_output_offload = __esm({
+  "src/exulu/tool-output-offload.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto3 = require("crypto");
+    init_uppy();
+    init_context_budget();
+    PREVIEW_CHARS = 4e3;
+    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}-${(0, import_node_crypto3.randomUUID)().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;
+      }
+    };
+    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.`;
+    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;
+    };
+    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
+var import_zod5, DEFAULT_LIMIT, MAX_CONTENT_CHARS, createSessionFileReadTool;
+var init_session_file_read_tool = __esm({
+  "src/templates/tools/session-file-read-tool.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_zod5 = require("zod");
+    init_tool();
+    init_uppy();
+    DEFAULT_LIMIT = 250;
+    MAX_CONTENT_CHARS = 16e3;
+    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: import_zod5.z.object({
+          filename: import_zod5.z.string().describe('Exact session file name as referenced in a truncation notice, e.g. "tool-output-web_search-a1b2c3d4.txt"'),
+          offset: import_zod5.z.number().int().min(1).optional().describe("1-based first line to read (default 1)"),
+          limit: import_zod5.z.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 convert_exulu_tools_to_ai_sdk_tools_exports = {};
 __export(convert_exulu_tools_to_ai_sdk_tools_exports, {
   convertExuluToolsToAiSdkTools: () => convertExuluToolsToAiSdkTools,
   hydrateVariables: () => hydrateVariables
 });
-var import_client_s32, import_crypto_js5, import_node_crypto3, generateS3Key, s3Client2, getMimeType, hydrateVariables, convertExuluToolsToAiSdkTools;
+var import_client_s32, import_crypto_js5, import_node_crypto4, OUTPUT_OFFLOAD_EXEMPT_TOOL_IDS, generateS3Key, s3Client2, getMimeType, hydrateVariables, convertExuluToolsToAiSdkTools;
 var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
   "src/templates/tools/convert-exulu-tools-to-ai-sdk-tools.ts"() {
     "use strict";
@@ -3950,17 +4156,21 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
     init_statistics2();
     init_client();
     import_crypto_js5 = __toESM(require("crypto-js"), 1);
-    init_project_retrieval_tool();
     init_session_items_retrieval_tool();
     init_pipeline();
+    init_project_scope();
     init_sanitize_tool_name();
-    import_node_crypto3 = require("crypto");
+    import_node_crypto4 = require("crypto");
     init_statistics();
     init_memory_tool();
     init_create_sandbox();
     init_uppy();
     init_truncate_tool_output();
-    generateS3Key = (filename) => `${(0, import_node_crypto3.randomUUID)()}-${filename}`;
+    init_tool_output_offload();
+    init_session_file_read_tool();
+    init_context_budget();
+    OUTPUT_OFFLOAD_EXEMPT_TOOL_IDS = /* @__PURE__ */ new Set(["agentic_context_search"]);
+    generateS3Key = (filename) => `${(0, import_node_crypto4.randomUUID)()}-${filename}`;
     getMimeType = (type) => {
       switch (type) {
         case ".png":
@@ -4057,7 +4267,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
       await Promise.all(promises2);
       return tool4;
     };
-    convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, providerapikey, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems) => {
+    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 = [];
@@ -4065,6 +4275,8 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
       if (!contexts) {
         contexts = [];
       }
+      const budget = deriveContextBudget(contextWindow);
+      const toolOutputCharLimit = budget.toolOutputCapTokens * 4;
       let sharedSessionSandbox;
       if (sessionID && exuluConfig && agent?.sandbox_enabled === true) {
         try {
@@ -4081,16 +4293,28 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
           );
         }
       }
-      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) {
@@ -4101,7 +4325,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
           );
         }
         const createNewMemoryTool = createNewMemoryItemTool(agent, context);
-        if (createNewMemoryTool) {
+        if (createNewMemoryTool && !disabled.has(createNewMemoryTool.id)) {
           if (!currentTools) {
             currentTools = [];
           }
@@ -4116,31 +4340,62 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
           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((tool4) => tool4.id === "agentic_context_search");
-          if (index !== -1) {
+      if (contexts?.length && model && !disabled.has("agentic_context_search")) {
+        const index = currentTools.findIndex((tool4) => tool4.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((tool4) => tool4.id === "agentic_context_search");
@@ -4168,7 +4423,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
             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;
@@ -4185,10 +4440,10 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
             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)
               }
             };
           }
@@ -4324,16 +4579,30 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
                   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;
                 }
               }
             }
@@ -4346,7 +4615,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
 });
 
 // src/exulu/tool.ts
-var import_ai3, import_zod6, import_node_crypto4, PUBLIC_TOOL_TYPES, ExuluTool;
+var import_ai3, import_zod6, import_node_crypto5, PUBLIC_TOOL_TYPES, ExuluTool;
 var init_tool = __esm({
   "src/exulu/tool.ts"() {
     "use strict";
@@ -4354,7 +4623,7 @@ var init_tool = __esm({
     import_ai3 = require("ai");
     import_zod6 = require("zod");
     init_sanitize_name();
-    import_node_crypto4 = require("crypto");
+    import_node_crypto5 = require("crypto");
     init_singleton();
     init_resolve_model();
     init_validate();
@@ -4481,7 +4750,7 @@ var init_tool = __esm({
           throw new Error("Tool " + sanitizeName(this.name) + " not found in " + JSON.stringify(tools));
         }
         console.log("[EXULU] Tool found", this.name);
-        const toolCallId = this.id + "_" + (0, import_node_crypto4.randomUUID)();
+        const toolCallId = this.id + "_" + (0, import_node_crypto5.randomUUID)();
         console.log("[EXULU] Calling tool execute", {
           inputs,
           toolCallId,
@@ -4675,6 +4944,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"]),
@@ -6002,6 +6272,7 @@ async function searchContexts(opts) {
     role,
     model,
     preselectedItems,
+    scopedItemsByContext,
     identifierPinsByContext,
     memoryPinnedItemIds,
     userPinnedItemIdsByContext,
@@ -6028,6 +6299,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);
@@ -6256,24 +6529,6 @@ var init_rerank = __esm({
 });
 
 // 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) {
@@ -6303,7 +6558,8 @@ function createAgenticRetrievalTool(opts) {
     model,
     instructions: adminInstructions,
     preselected,
-    memoryItems
+    memoryItems,
+    projectScope
   } = opts;
   const license = checkLicense();
   if (!license["agentic-retrieval"]) {
@@ -6313,7 +6569,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",
@@ -6356,10 +6614,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.",
@@ -6469,6 +6733,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) => [
@@ -6479,7 +6760,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 ?? [],
@@ -6525,6 +6811,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,
@@ -6551,7 +6861,7 @@ function createAgenticRetrievalTool(opts) {
         }
         const [mainSearch, speculativeFallbackSearch] = await Promise.all([
           searchContexts({
-            contextIds: mainContexts,
+            contextIds: effectiveMainContexts,
             contextsById,
             kbProfiles: cfg.knowledgeBases,
             question: updatedQuestion,
@@ -6564,13 +6874,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,
@@ -6583,6 +6894,7 @@ function createAgenticRetrievalTool(opts) {
             identifierPinsByContext,
             memoryPinnedItemIds,
             userPinnedItemIdsByContext,
+            scopedItemsByContext: resolvedProject?.scopedItemsByContext,
             rewrites: cfg.vocabulary.rewrites,
             styleHint: cfg.vocabulary.styleHint,
             maxQueries: cfg.tuning.maxQueriesPerContext,
@@ -6596,6 +6908,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(
@@ -6663,15 +6978,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,
@@ -6747,11 +7062,14 @@ var init_pipeline = __esm({
     init_resolve_model();
     init_singleton();
     init_config();
+    init_project_scope();
     init_routing();
     init_memory();
     init_prefilter();
     init_search();
     init_rerank();
+    init_global_ids();
+    init_global_ids();
   }
 });
 
@@ -9086,6 +9404,13 @@ var agentsSchema = {
       name: "sandbox_enabled",
       type: "boolean",
       default: false
+    },
+    {
+      // Per-turn budget for ALL tool steps on one chat message (bash, files,
+      // knowledge search, integrations). 0/null = platform default
+      // (DEFAULT_MAX_STEPS in resolve-max-steps.ts). Auto-ALTERed on boot.
+      name: "max_tool_steps",
+      type: "number"
     }
   ]
 };
@@ -11148,7 +11473,7 @@ var ExuluContext2 = class {
     embedder,
     chunker,
     processor,
-    active,
+    active: active2,
     fields,
     queryRewriter,
     resultReranker,
@@ -11179,7 +11504,7 @@ var ExuluContext2 = class {
     this.description = description;
     this.embedder = embedder;
     this.chunker = chunker;
-    this.active = active;
+    this.active = active2;
     this.queryRewriter = queryRewriter;
     this.resultReranker = resultReranker;
     this.entities = entities;
@@ -12179,7 +12504,6 @@ init_cjs_shims();
 init_pipeline();
 init_check_record_access();
 init_client();
-init_project_retrieval_tool();
 init_singleton();
 init_supervisor();
 init_catalog();
@@ -12326,14 +12650,26 @@ var addProviderFields = async (args, requestedFields, providers, result, tools,
         )
       );
       if (args.project) {
-        const projectTool = await createProjectItemsRetrievalTool({
-          projectId: args.project,
-          user,
-          role: user.role?.id,
-          contexts
-        });
-        if (projectTool) {
-          result.tools.unshift(projectTool);
+        const hasAgentic = result.tools.some(
+          (tool4) => tool4?.id === "agentic_context_search"
+        );
+        if (!hasAgentic) {
+          const instance2 = createAgenticRetrievalTool({
+            contexts: [],
+            user,
+            role: user.role?.id,
+            model: void 0
+          });
+          if (instance2) {
+            result.tools.unshift({
+              id: instance2.id,
+              name: instance2.name,
+              description: instance2.description,
+              category: instance2.category,
+              type: instance2.type,
+              config: []
+            });
+          }
         }
       }
       result.tools = result.tools.filter((tool4) => tool4 !== null);
@@ -18259,11 +18595,11 @@ var import_body_parser = __toESM(require("body-parser"), 1);
 var import_crypto_js9 = __toESM(require("crypto-js"), 1);
 var import_openai = __toESM(require("openai"), 1);
 var import_fs3 = __toESM(require("fs"), 1);
-var import_node_crypto7 = require("crypto");
+var import_node_crypto9 = require("crypto");
 var import_api2 = require("@opentelemetry/api");
 init_check_record_access();
 var import_jszip2 = __toESM(require("jszip"), 1);
-var import_ai14 = require("ai");
+var import_ai15 = require("ai");
 var import_cookie_parser = __toESM(require("cookie-parser"), 1);
 init_statistics2();
 
@@ -18272,7 +18608,8 @@ init_cjs_shims();
 
 // src/exulu/resolve-max-steps.ts
 init_cjs_shims();
-function resolveMaxStepsFromToolConfigs(toolConfigs) {
+var DEFAULT_MAX_STEPS = 10;
+function resolveRetrievalCallBudget(toolConfigs) {
   const agentic = toolConfigs?.find((t) => t.id === "agentic_context_search");
   if (!agentic?.config) return void 0;
   const entry = agentic.config.find((c) => c.name === "max_steps");
@@ -18281,15 +18618,26 @@ function resolveMaxStepsFromToolConfigs(toolConfigs) {
   const n = typeof raw === "number" ? raw : parseInt(String(raw ?? ""), 10);
   return Number.isFinite(n) && n > 0 ? Math.floor(n) : void 0;
 }
+function resolveTurnStepBudget(maxStepCount, agent) {
+  if (typeof maxStepCount === "number" && Number.isFinite(maxStepCount) && maxStepCount > 0) {
+    return Math.floor(maxStepCount);
+  }
+  const raw = agent?.max_tool_steps;
+  const n = typeof raw === "number" ? raw : parseInt(String(raw ?? ""), 10);
+  if (Number.isFinite(n) && n > 0) {
+    return Math.floor(n);
+  }
+  return DEFAULT_MAX_STEPS;
+}
 function flattenPart(part) {
   const p = part;
   if (p?.type === "text") return p.text ?? "";
   if (p?.type === "tool-call") {
-    return `[searched ${p.toolName}: ${JSON.stringify(p.input ?? {}).slice(0, 300)}]`;
+    return `Earlier, the assistant ran the "${p.toolName}" tool with input: ${JSON.stringify(p.input ?? {}).slice(0, 300)}`;
   }
   if (p?.type === "tool-result") {
     const out = p.output?.value ?? p.output;
-    return `[results from ${p.toolName}]: ${typeof out === "string" ? out : JSON.stringify(out ?? "")}`;
+    return `The "${p.toolName}" tool returned: ${typeof out === "string" ? out : JSON.stringify(out ?? "")}`;
   }
   return "";
 }
@@ -18307,7 +18655,7 @@ function flattenToolHistory(messages) {
     return m;
   });
 }
-var FINAL_ANSWER_INSTRUCTION = "Answer the user's original question now, in plain text, using only the material already retrieved above. Do not attempt any further tool calls.";
+var FINAL_ANSWER_INSTRUCTION = `This is your last step for this turn. Answer the user's original question now, in plain text, using only the information gathered above. If you could not finish the task, tell the user you reached the maximum number of tool steps, summarize what you found and did so far, and say what remains \u2014 they can ask you to continue. Do not attempt any further tool calls. Write your answer as normal prose for the user: do not output tool-call syntax, JSON commands, or bracketed lines such as "[called tool ...]" \u2014 describe anything you did or still plan to do in plain language.`;
 function finalAnswerGuard(maxSteps) {
   return ({ stepNumber, messages }) => stepNumber >= maxSteps - 1 ? {
     toolChoice: "none",
@@ -18320,6 +18668,73 @@ function finalAnswerGuard(maxSteps) {
     } : {}
   } : void 0;
 }
+function retrievalBudgetGuard(limit, agenticToolKey, allToolKeys) {
+  if (limit == null || limit <= 0 || !agenticToolKey || !allToolKeys.includes(agenticToolKey)) {
+    return () => void 0;
+  }
+  const remainingTools = allToolKeys.filter((k) => k !== agenticToolKey);
+  return ({ steps }) => {
+    const calls = (steps ?? []).flatMap((s) => s?.toolCalls ?? []).filter((c) => c?.toolName === agenticToolKey).length;
+    if (calls < limit) return void 0;
+    return { activeTools: remainingTools };
+  };
+}
+
+// src/exulu/context-guard.ts
+init_cjs_shims();
+init_context_budget();
+var KEEP_RECENT_TOOL_MESSAGES = 2;
+var COLLAPSE_KEEP_CHARS = 400;
+var COLLAPSE_MARKER = " \u2026[older tool output collapsed mid-response to fit the context window \u2014 the full output is in the session file named in the notice above, if one was saved]";
+function contextGuard(contextWindow) {
+  const budget = deriveContextBudget(contextWindow);
+  return async ({ messages }) => {
+    if (!Array.isArray(messages) || messages.length === 0) return void 0;
+    const tokens = estimateTokens(JSON.stringify(messages));
+    if (tokens < budget.usableWindow) return void 0;
+    const toolIndices = messages.map((m, i) => m?.role === "tool" ? i : -1).filter((i) => i !== -1);
+    const collapsible = new Set(toolIndices.slice(0, Math.max(0, toolIndices.length - KEEP_RECENT_TOOL_MESSAGES)));
+    if (collapsible.size === 0) return void 0;
+    let changed = false;
+    const next = messages.map((m, i) => {
+      if (!collapsible.has(i)) return m;
+      const msg = m;
+      if (!Array.isArray(msg.content)) return m;
+      const content = msg.content.map((part) => {
+        const p = part;
+        if (p?.type !== "tool-result") return part;
+        const out = p.output?.value ?? p.output;
+        const asText = typeof out === "string" ? out : JSON.stringify(out ?? "");
+        if (asText.length <= COLLAPSE_KEEP_CHARS + COLLAPSE_MARKER.length) return part;
+        changed = true;
+        return { ...part, output: { type: "text", value: asText.slice(0, COLLAPSE_KEEP_CHARS) + COLLAPSE_MARKER } };
+      });
+      return { ...m, content };
+    });
+    return changed ? { messages: next } : void 0;
+  };
+}
+function composePrepareSteps(...guards) {
+  return async (opts) => {
+    let merged;
+    let messages = opts.messages;
+    for (const guard of guards) {
+      const result = await guard({ ...opts, messages });
+      if (!result) continue;
+      merged = { ...merged ?? {}, ...result };
+      if (Array.isArray(result.messages)) {
+        messages = result.messages;
+      }
+    }
+    if (merged && messages && !("messages" in merged)) {
+      merged.messages = messages;
+    }
+    return merged;
+  };
+}
+
+// src/exulu/provider.ts
+init_sanitize_tool_name();
 
 // src/exulu/auto-decline-stale-approvals.ts
 init_cjs_shims();
@@ -18419,6 +18834,8 @@ async function clearSessionCurrentTask(session) {
 }
 
 // src/exulu/provider.ts
+init_context_budget();
+init_tool_output_offload();
 var ExuluProvider = class {
   // Must begin with a letter (a-z) or underscore (_). Subsequent characters in a name can be letters, digits (0-9), or
   // underscores and be a max length of 80 characters and at least 5 characters long.
@@ -18589,7 +19006,9 @@ var ExuluProvider = class {
     agent,
     instructions,
     maxStepCount,
-    onTokenUsage
+    onTokenUsage,
+    contextWindow,
+    disabledTools
   }) => {
     console.log(
       "[EXULU] Called generate sync for agent: " + this.name,
@@ -18617,9 +19036,7 @@ var ExuluProvider = class {
     if (messages && session && user) {
       const previousMessages = await getAgentMessages({
         session,
-        user: user.id,
-        limit: 50,
-        page: 1
+        user: user.id
       });
       const previousMessagesContent = previousMessages.map(
         (message) => JSON.parse(message.content)
@@ -18628,6 +19045,12 @@ var ExuluProvider = class {
         // append the new message to the previous messages:
         messages: [...previousMessagesContent, ...messages]
       });
+      const contextBudget = deriveContextBudget(contextWindow);
+      const occupancy = contextOccupancy(messages);
+      if (occupancy >= contextBudget.blockThreshold) {
+        throw new ContextCompactionRequiredError(occupancy, contextBudget);
+      }
+      messages = sliceHistoryAtCheckpoint(messages);
     }
     console.log(
       "[EXULU] Message count for agent: " + this.name,
@@ -18692,6 +19115,34 @@ var ExuluProvider = class {
     if (memoryContext) {
       system += "\n\n" + memoryContext;
     }
+    const tools = await convertExuluToolsToAiSdkTools(
+      currentTools,
+      currentSkills,
+      approvedTools,
+      allExuluTools,
+      toolConfigs,
+      providerapikey,
+      contexts,
+      user,
+      exuluConfig,
+      session,
+      req,
+      project,
+      sessionItems,
+      model,
+      agent,
+      memoryItems,
+      contextWindow,
+      disabledTools
+    );
+    const agenticEntry = currentTools?.find((t) => t.id === "agentic_context_search");
+    const agenticToolKey = agenticEntry ? sanitizeToolName(agenticEntry.name) : void 0;
+    const retrievalGuard = retrievalBudgetGuard(
+      resolveRetrievalCallBudget(toolConfigs),
+      agenticToolKey,
+      Object.keys(tools)
+    );
+    const turnBudget = resolveTurnStepBudget(maxStepCount, agent);
     const includesContextSearchTool = currentTools?.some(
       (tool4) => tool4.name.toLowerCase().includes("context_search") || tool4.id.includes("context_search") || tool4.type === "context"
     );
@@ -18704,12 +19155,12 @@ var ExuluProvider = class {
       system += `
 
 
-  
+
               When you use a context search tool, you will include references to the items
               retrieved from the tool call result inline in the response using this exact JSON format
               (all on one line, no line breaks):
               {item_name: <item_name>, item_id: <item_id>, context: <context_id>, chunk_id: <chunk_id>, chunk_index: <chunk_index>}
-  
+
               IMPORTANT formatting rules:
               - Do NOT reference just chunks like "Looking at chunk_index 5 and chunk_index 0 from the search result", always use the JSON format above.
               - Use the exact format shown above, all on ONE line
@@ -18717,9 +19168,9 @@ var ExuluProvider = class {
               - Use the context ID from the tool result
               - Include the file/item name, not the full path
               - Separate multiple citations with spaces
-  
+
               Example: {item_name: document.pdf, item_id: abc123, context: my-context-id, chunk_id: chunk_456, chunk_index: 0}
-  
+
               The citations will be rendered as interactive badges in the UI.
               `;
     }
@@ -18730,12 +19181,12 @@ var ExuluProvider = class {
               When you use a web search tool, you will include references to the results of the tool call result inline in the response using this exact JSON format
               (all on one line, no line breaks):
               {url: <url>, title: <title>, snippet: <snippet>}
-  
+
               IMPORTANT formatting rules:
               - Use the exact format shown above, all on ONE line
               - Do NOT use quotes around field names or values
               - Separate multiple results with spaces
-  
+
               Example: {url: https://www.google.com, title: Google, snippet: The result of the web search.}
               `;
     }
@@ -18768,29 +19219,12 @@ When a tool execution is not approved by the user, do not retry it unless explic
         system,
         prompt,
         maxRetries: 2,
-        tools: await convertExuluToolsToAiSdkTools(
-          currentTools,
-          currentSkills,
-          approvedTools,
-          allExuluTools,
-          toolConfigs,
-          providerapikey,
-          contexts,
-          user,
-          exuluConfig,
-          session,
-          req,
-          project,
-          sessionItems,
-          model,
-          agent,
-          memoryItems
-        ),
+        tools,
         // Stop after the image_generation tool fires — the widget IS the
         // assistant's response, no follow-up text turn is wanted (same
         // reasoning as question_ask: the UI artifact is the message).
-        prepareStep: finalAnswerGuard(maxStepCount ?? resolveMaxStepsFromToolConfigs(toolConfigs) ?? 5),
-        stopWhen: [(0, import_ai11.stepCountIs)(maxStepCount ?? resolveMaxStepsFromToolConfigs(toolConfigs) ?? 5), (0, import_ai11.hasToolCall)("image_generation")]
+        prepareStep: composePrepareSteps(contextGuard(contextWindow), retrievalGuard, finalAnswerGuard(turnBudget)),
+        stopWhen: [(0, import_ai11.stepCountIs)(turnBudget), (0, import_ai11.hasToolCall)("image_generation")]
       });
       console.log("[EXULU] Output: " + JSON.stringify(output, null, 2));
       const {
@@ -18851,26 +19285,9 @@ When a tool execution is not approved by the user, do not retry it unless explic
           ignoreIncompleteToolCalls: true
         }),
         maxRetries: 2,
-        tools: await convertExuluToolsToAiSdkTools(
-          currentTools,
-          currentSkills,
-          approvedTools,
-          allExuluTools,
-          toolConfigs,
-          providerapikey,
-          contexts,
-          user,
-          exuluConfig,
-          session,
-          req,
-          project,
-          sessionItems,
-          model,
-          agent,
-          memoryItems
-        ),
-        prepareStep: finalAnswerGuard(maxStepCount ?? resolveMaxStepsFromToolConfigs(toolConfigs) ?? 5),
-        stopWhen: [(0, import_ai11.stepCountIs)(maxStepCount ?? resolveMaxStepsFromToolConfigs(toolConfigs) ?? 5), (0, import_ai11.hasToolCall)("image_generation")]
+        tools,
+        prepareStep: composePrepareSteps(contextGuard(contextWindow), retrievalGuard, finalAnswerGuard(turnBudget)),
+        stopWhen: [(0, import_ai11.stepCountIs)(turnBudget), (0, import_ai11.hasToolCall)("image_generation")]
       });
       if (statistics) {
         await Promise.all([
@@ -18922,7 +19339,7 @@ When a tool execution is not approved by the user, do not retry it unless explic
    * - Document files (PDF, DOCX, etc.) -> text parts with extracted content using officeparser
    * - Image files -> image parts (which ARE supported by Responses API)
    */
-  async processFilePartsInMessages(messages) {
+  async processFilePartsInMessages(messages, offloadCtx) {
     const processedMessages = await Promise.all(
       messages.map(async (message) => {
         if (message.role !== "user" || !Array.isArray(message.parts)) {
@@ -18967,10 +19384,11 @@ When a tool execution is not approved by the user, do not retry it unless explic
                 outputErrorToConsole: false,
                 newlineDelimiter: "\n"
               });
+              const guardedText = await guardExtractedFileText(filename, String(extractedText), offloadCtx);
               return {
                 type: "text",
                 text: `<file file name = "${filename}" >
-${extractedText} 
+${guardedText} 
  </file>`
               };
             } catch (error) {
@@ -18986,7 +19404,6 @@ ${extractedText}
           ...message,
           parts: processedParts
         };
-        console.log("[EXULU] Result: " + JSON.stringify(result, null, 2));
         return result;
       })
     );
@@ -19009,7 +19426,9 @@ ${extractedText}
     exuluConfig,
     instructions,
     req,
-    maxStepCount
+    maxStepCount,
+    contextWindow,
+    disabledTools
   }) => {
     if (!this.config) {
       console.error("[EXULU] Config is required for streaming.");
@@ -19030,9 +19449,7 @@ ${extractedText}
       console.log("[EXULU] loading previous messages from session: " + session);
       const previousMessages2 = await getAgentMessages({
         session,
-        user: user?.id,
-        limit: 50,
-        page: 1
+        user: user?.id
       });
       previousMessagesContent = previousMessages2.map((message2) => JSON.parse(message2.content));
     }
@@ -19091,64 +19508,32 @@ ${extractedText}
       (message2, index, self) => index === self.findLastIndex((t) => t.id === message2.id)
     );
     const { messages: reconciledMessages, declined } = autoDeclineStaleApprovals(messages);
-    messages = reconciledMessages;
-    if (declined.length && session && user) {
-      await saveChat({ session, user: user.id, messages: declined });
-    }
-    messages = await this.processFilePartsInMessages(messages);
-    const genericContext = "IMPORTANT: \n\n The current date is " + (/* @__PURE__ */ new Date()).toLocaleDateString() + " and the current time is " + (/* @__PURE__ */ new Date()).toLocaleTimeString() + ". If the user does not explicitly provide the current date, for examle when saying ' this weekend', you should assume they are talking with the current date in mind as a reference.";
-    let system = instructions || "You are a helpful assistant. When you use a tool to answer a question do not explicitly comment on the result of the tool call unless the user has explicitly you to do something with the result.";
-    if (user?.personal_system_prompt?.trim()) {
-      system += "\n\nUser preferences:\n" + user.personal_system_prompt.trim();
-    }
-    system += "\n\n" + genericContext;
-    const includesContextSearchTool = currentTools?.some(
-      (tool4) => tool4.name.toLowerCase().includes("context_search") || tool4.id.includes("context_search") || tool4.type === "context"
-    );
-    const includesWebSearchTool = currentTools?.some(
-      (tool4) => tool4.name.toLowerCase().includes("web_search") || tool4.id.includes("web_search") || tool4.type === "web_search"
-    );
-    console.log("[EXULU] Current tools: " + currentTools?.map((tool4) => tool4.name).join("\n"));
-    console.log("[EXULU] Includes context search tool: " + includesContextSearchTool);
-    console.log("[EXULU] Includes web search tool: " + includesWebSearchTool);
-    if (includesContextSearchTool) {
-      system += `
-
-
-  
-              When you use a context search tool, you will include references to the items
-              retrieved from the tool call result inline in the response using this exact JSON format
-              (all on one line, no line breaks):
-              {item_name: <item_name>, item_id: <item_id>, context: <context_id>, chunk_id: <chunk_id>, chunk_index: <chunk_index>}
-  
-              IMPORTANT formatting rules:
-              - Use the exact format shown above, all on ONE line
-              - Do NOT use quotes around field names or values
-              - Use the context ID from the tool result
-              - Include the file/item name, not the full path
-              - Separate multiple citations with spaces
-  
-              Example: {item_name: document.pdf, item_id: abc123, context: my-context-id, chunk_id: chunk_456, chunk_index: 0}
-  
-              The citations will be rendered as interactive badges in the UI.
-              `;
-    }
-    if (includesWebSearchTool) {
-      system += `
-
-
-              When you use a web search tool, you will include references to the results of the tool call result inline in the response using this exact JSON format
-              (all on one line, no line breaks):
-              {url: <url>, title: <title>, snippet: <snippet>}
-  
-              IMPORTANT formatting rules:
-              - Use the exact format shown above, all on ONE line
-              - Do NOT use quotes around field names or values
-              - Separate multiple results with spaces
-  
-              Example: {url: https://www.google.com, title: Google, snippet: The result of the web search.}
-              `;
+    messages = reconciledMessages;
+    if (declined.length && session && user) {
+      await saveChat({ session, user: user.id, messages: declined });
+    }
+    messages = await this.processFilePartsInMessages(messages, {
+      contextWindow,
+      sessionID: session,
+      user,
+      exuluConfig
+    });
+    const chronologicalMessages = messages;
+    const contextBudget = deriveContextBudget(contextWindow);
+    const occupancy = contextOccupancy(chronologicalMessages);
+    if (occupancy >= contextBudget.blockThreshold) {
+      console.warn(
+        `[EXULU] Blocking request: occupancy ${occupancy} >= blockThreshold ${contextBudget.blockThreshold} (window ${contextBudget.contextWindow}).`
+      );
+      throw new ContextCompactionRequiredError(occupancy, contextBudget);
+    }
+    messages = sliceHistoryAtCheckpoint(chronologicalMessages);
+    const genericContext = "IMPORTANT: \n\n The current date is " + (/* @__PURE__ */ new Date()).toLocaleDateString() + " and the current time is " + (/* @__PURE__ */ new Date()).toLocaleTimeString() + ". If the user does not explicitly provide the current date, for examle when saying ' this weekend', you should assume they are talking with the current date in mind as a reference.";
+    let system = instructions || "You are a helpful assistant. When you use a tool to answer a question do not explicitly comment on the result of the tool call unless the user has explicitly you to do something with the result.";
+    if (user?.personal_system_prompt?.trim()) {
+      system += "\n\nUser preferences:\n" + user.personal_system_prompt.trim();
     }
+    system += "\n\n" + genericContext;
     if (currentSkills?.length) {
       const skillsList = currentSkills.map((skill) => {
         const description = (skill.description ?? "").trim();
@@ -19203,6 +19588,11 @@ ${skillsList}
         read them with the readFile tool. Files you produce yourself (via writeFile or via shell
         commands like \`node create_doc.js\`) live in the same place. These files are scoped to
         this single session; they are NOT visible in other sessions, projects, or knowledge bases.
+
+        Note on large outputs: oversized tool outputs and large uploaded documents are automatically
+        truncated in the conversation; the FULL content is saved as a session file (named in the
+        truncation notice, e.g. tool-output-*.txt). Use the read_session_file tool with offset/limit
+        to page through it \u2014 do not ask the user to re-upload.
       `;
     system += `
 
@@ -19226,9 +19616,66 @@ When a tool execution is not approved by the user, do not retry it unless explic
       sessionItems,
       model,
       agent,
-      memoryItems
+      memoryItems,
+      contextWindow,
+      disabledTools
     );
     console.log("[EXULU] Converted tools", Object.keys(tools));
+    const includesContextSearchTool = currentTools?.some(
+      (tool4) => tool4.name.toLowerCase().includes("context_search") || tool4.id.includes("context_search") || tool4.type === "context"
+    );
+    const includesWebSearchTool = currentTools?.some(
+      (tool4) => tool4.name.toLowerCase().includes("web_search") || tool4.id.includes("web_search") || tool4.type === "web_search"
+    );
+    console.log("[EXULU] Current tools: " + currentTools?.map((tool4) => tool4.name).join("\n"));
+    console.log("[EXULU] Includes context search tool: " + includesContextSearchTool);
+    console.log("[EXULU] Includes web search tool: " + includesWebSearchTool);
+    if (includesContextSearchTool) {
+      system += `
+
+
+
+              When you use a context search tool, you will include references to the items
+              retrieved from the tool call result inline in the response using this exact JSON format
+              (all on one line, no line breaks):
+              {item_name: <item_name>, item_id: <item_id>, context: <context_id>, chunk_id: <chunk_id>, chunk_index: <chunk_index>}
+
+              IMPORTANT formatting rules:
+              - Use the exact format shown above, all on ONE line
+              - Do NOT use quotes around field names or values
+              - Use the context ID from the tool result
+              - Include the file/item name, not the full path
+              - Separate multiple citations with spaces
+
+              Example: {item_name: document.pdf, item_id: abc123, context: my-context-id, chunk_id: chunk_456, chunk_index: 0}
+
+              The citations will be rendered as interactive badges in the UI.
+              `;
+    }
+    if (includesWebSearchTool) {
+      system += `
+
+
+              When you use a web search tool, you will include references to the results of the tool call result inline in the response using this exact JSON format
+              (all on one line, no line breaks):
+              {url: <url>, title: <title>, snippet: <snippet>}
+
+              IMPORTANT formatting rules:
+              - Use the exact format shown above, all on ONE line
+              - Do NOT use quotes around field names or values
+              - Separate multiple results with spaces
+
+              Example: {url: https://www.google.com, title: Google, snippet: The result of the web search.}
+              `;
+    }
+    const agenticEntry = currentTools?.find((t) => t.id === "agentic_context_search");
+    const agenticToolKey = agenticEntry ? sanitizeToolName(agenticEntry.name) : void 0;
+    const retrievalGuard = retrievalBudgetGuard(
+      resolveRetrievalCallBudget(toolConfigs),
+      agenticToolKey,
+      Object.keys(tools)
+    );
+    const turnBudget = resolveTurnStepBudget(maxStepCount, agent);
     const result = (0, import_ai11.streamText)({
       temperature: 0,
       // TODO Make this configurable
@@ -19253,10 +19700,9 @@ When a tool execution is not approved by the user, do not retry it unless explic
           `Chat stream error: ${error instanceof Error ? error.message : JSON.stringify(error)}`
         );
       },
-      // provide more loops for skills because they are more complex to execute
-      // todo allow configuring this per skill
-      prepareStep: finalAnswerGuard(maxStepCount ?? resolveMaxStepsFromToolConfigs(toolConfigs) ?? (currentSkills?.length ? 10 : 5)),
-      stopWhen: [(0, import_ai11.stepCountIs)(maxStepCount ?? resolveMaxStepsFromToolConfigs(toolConfigs) ?? (currentSkills?.length ? 10 : 5)), (0, import_ai11.hasToolCall)("image_generation")]
+      // todo allow configuring the step budget per skill
+      prepareStep: composePrepareSteps(contextGuard(contextWindow), retrievalGuard, finalAnswerGuard(turnBudget)),
+      stopWhen: [(0, import_ai11.stepCountIs)(turnBudget), (0, import_ai11.hasToolCall)("image_generation")]
     });
     return {
       stream: result,
@@ -19267,19 +19713,14 @@ When a tool execution is not approved by the user, do not retry it unless explic
 };
 var getAgentMessages = async ({
   session,
-  user,
-  limit,
-  page
+  user
 }) => {
   const { db: db2 } = await postgresClient();
-  console.log(
-    "[EXULU] getting agent messages for session: " + session + " and user: " + user + " and page: " + page
-  );
-  const query = db2.from("agent_messages").where({ session, user: user || null }).limit(limit);
-  if (page > 0) {
-    query.offset((page - 1) * limit);
-  }
-  const messages = await query;
+  console.log("[EXULU] getting agent messages for session: " + session + " and user: " + user);
+  const messages = await db2.from("agent_messages").where({ session, user: user || null }).orderBy([
+    { column: "createdAt", order: "asc" },
+    { column: "id", order: "asc" }
+  ]);
   return messages;
 };
 var getSession = async ({ sessionID }) => {
@@ -19383,6 +19824,161 @@ ${SUGGESTIONS_SYSTEM_PROMPT}` : SUGGESTIONS_SYSTEM_PROMPT;
 init_resolve_model();
 init_supervisor();
 
+// src/exulu/resolve-context-window.ts
+init_cjs_shims();
+init_catalog();
+init_context_budget();
+var resolveContextWindow = async ({
+  modelId,
+  exuluProvider
+}) => {
+  if (process.env.EXULU_USE_LITELLM === "true") {
+    const entry = await findLiteLLMModel(modelId);
+    const fromCatalog = entry?.max_input_tokens ?? entry?.max_tokens;
+    if (fromCatalog != null && fromCatalog > 0) return fromCatalog;
+  } else if (exuluProvider) {
+    try {
+      const fromProvider = exuluProvider.maxContextLength;
+      if (fromProvider != null && fromProvider > 0) return fromProvider;
+    } catch {
+    }
+  }
+  console.warn(
+    `[EXULU] Unknown context window for model "${modelId}" \u2014 assuming ${DEFAULT_CONTEXT_WINDOW}. Check the LiteLLM catalog / provider template metadata.`
+  );
+  return DEFAULT_CONTEXT_WINDOW;
+};
+
+// src/exulu/routes.ts
+init_context_budget();
+
+// src/exulu/active-streams.ts
+init_cjs_shims();
+var active = /* @__PURE__ */ new Set();
+var markStreamActive = (sessionID) => {
+  active.add(sessionID);
+};
+var clearStreamActive = (sessionID) => {
+  active.delete(sessionID);
+};
+var isStreamActive = (sessionID) => active.has(sessionID);
+
+// src/exulu/compact-session.ts
+init_cjs_shims();
+var import_node_crypto6 = require("crypto");
+var import_ai13 = require("ai");
+init_truncate_tool_output();
+init_context_budget();
+var CompactionInsufficientError = class extends Error {
+  constructor(reason) {
+    super(JSON.stringify({ code: COMPACTION_INSUFFICIENT, message: reason }));
+    this.name = "CompactionInsufficientError";
+  }
+};
+var MIN_TAIL_MESSAGES = 2;
+var SUMMARY_TOOL_OUTPUT_SLICE = 1500;
+var SUMMARY_TOOL_INPUT_SLICE = 200;
+var SUMMARY_SYSTEM = `You compress chat histories for an AI assistant. Produce a dense, factual summary of the conversation below. Preserve:
+- the user's intent and any outstanding requests
+- key facts, decisions, and constraints
+- files, artifacts, and session files touched \u2014 ALWAYS keep exact file and item names so they stay retrievable
+- errors encountered and how they were resolved
+- pending tasks and the current state of the work
+Do not invent information. Do not include pleasantries. Write compact prose or bullet points.`;
+var splitTail = (messages, tailTokenBudget) => {
+  const minTail = Math.min(MIN_TAIL_MESSAGES, messages.length);
+  let cut = messages.length;
+  let tokens = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const t = estimateMessageTokens(messages[i]);
+    const tailCount = messages.length - i;
+    if (tailCount > minTail && tokens + t > tailTokenBudget) break;
+    tokens += t;
+    cut = i;
+  }
+  return { head: messages.slice(0, cut), tail: messages.slice(cut) };
+};
+var serializeForSummary = (messages) => messages.map((m) => {
+  const parts = (m.parts ?? []).map((part) => {
+    const p = part;
+    if (p.type === "text") return p.text ?? "";
+    if (p.type === "file") return `[file: ${p.filename ?? p.url ?? "attachment"}]`;
+    if (p.type === "reasoning" || p.type === "step-start") return "";
+    if (p.type?.startsWith("tool-") || p.type === "dynamic-tool") {
+      const out = p.output?.value ?? p.output;
+      const outText = typeof out === "string" ? out : JSON.stringify(out ?? "");
+      return `[tool ${p.type}: ${JSON.stringify(p.input ?? {}).slice(0, SUMMARY_TOOL_INPUT_SLICE)}] \u2192 ${outText.slice(0, SUMMARY_TOOL_OUTPUT_SLICE)}`;
+    }
+    return "";
+  }).filter(Boolean).join("\n");
+  return `${m.role.toUpperCase()}:
+${parts}`;
+}).join("\n\n");
+var compactSession = async ({
+  sessionID,
+  user,
+  languageModel,
+  contextWindow,
+  steer,
+  modelId,
+  summarize
+}) => {
+  const budget = deriveContextBudget(contextWindow);
+  const rows = await getAgentMessages({ session: sessionID, user: user.id });
+  const all = await (0, import_ai13.validateUIMessages)({ messages: rows.map((r) => JSON.parse(r.content)) });
+  const history = sliceHistoryAtCheckpoint(all);
+  const { head, tail } = splitTail(history, budget.compactionTailTokens);
+  if (head.length === 0) {
+    throw new CompactionInsufficientError(
+      "There is nothing left to compact \u2014 the recent messages already form the whole context. Start a new chat instead."
+    );
+  }
+  let corpus = serializeForSummary(head);
+  const originalTokens = estimateTokens(corpus);
+  corpus = truncateToolOutput(corpus, contextWindow, "history", 0.3, Math.floor(budget.usableWindow * 0.8) * 4);
+  const system = steer?.trim() ? `${SUMMARY_SYSTEM}
+
+Focus especially on: ${steer.trim()}` : SUMMARY_SYSTEM;
+  const doSummarize = summarize ?? (async ({ system: sys, prompt, maxOutputTokens }) => {
+    const { text } = await (0, import_ai13.generateText)({
+      model: languageModel,
+      system: sys,
+      prompt,
+      temperature: 0,
+      maxRetries: 2,
+      maxOutputTokens
+    });
+    return text;
+  });
+  const summary = await doSummarize({ system, prompt: corpus, maxOutputTokens: budget.summaryBudgetTokens });
+  const summaryTokens = estimateTokens(summary);
+  let tailTokens = 0;
+  for (const m of tail) tailTokens += estimateMessageTokens(m);
+  const occupancyEstimate = summaryTokens + tailTokens;
+  if (occupancyEstimate >= budget.blockThreshold) {
+    throw new CompactionInsufficientError(
+      "Compacting cannot shrink this conversation below the context limit \u2014 a recent message or output is too large by itself. Start a new chat."
+    );
+  }
+  const compaction = {
+    coversUpTo: head[head.length - 1].id,
+    originalTokens,
+    summaryTokens,
+    occupancyEstimate,
+    ...steer?.trim() ? { steer: steer.trim() } : {}
+  };
+  const checkpoint = {
+    id: `compaction_${(0, import_node_crypto6.randomUUID)()}`,
+    role: "user",
+    parts: [{ type: "text", text: `[Conversation summary \u2014 earlier messages were compacted]
+
+${summary}` }],
+    metadata: { compaction }
+  };
+  await saveChat({ session: sessionID, user: user.id, messages: [checkpoint], ...modelId ? { model: modelId } : {} });
+  return { checkpoint, occupancyEstimate, originalTokens, summaryTokens };
+};
+
 // src/exulu/transcribe.ts
 init_cjs_shims();
 var TranscriptionError = class extends Error {
@@ -19757,7 +20353,7 @@ function checkApiKeyScope(user, agentId) {
 // src/exulu/openai-gateway.ts
 init_cjs_shims();
 var import_express2 = require("express");
-var import_ai13 = require("ai");
+var import_ai14 = require("ai");
 
 // src/exulu/openai-transformer.ts
 init_cjs_shims();
@@ -19845,7 +20441,7 @@ function transformCompletion(text, inputTokens, outputTokens, ctx) {
 }
 
 // src/exulu/openai-gateway.ts
-var import_node_crypto5 = require("crypto");
+var import_node_crypto7 = require("crypto");
 var import_crypto_js8 = require("crypto-js");
 var import_express3 = __toESM(require("express"), 1);
 init_client();
@@ -19853,6 +20449,9 @@ init_convert_exulu_tools_to_ai_sdk_tools();
 init_statistics2();
 init_statistics();
 init_resolve_model();
+init_sanitize_tool_name();
+init_context_budget();
+init_supervisor();
 function convertOpenAIToolsToAiSdkTools(tools) {
   return Object.fromEntries(
     tools.map((t) => {
@@ -19861,7 +20460,7 @@ function convertOpenAIToolsToAiSdkTools(tools) {
         t.function.name,
         {
           description: t.function.description ?? "",
-          inputSchema: (0, import_ai13.jsonSchema)({
+          inputSchema: (0, import_ai14.jsonSchema)({
             type: "object",
             properties: params.properties ?? {},
             ...params.required ? { required: params.required } : {}
@@ -20164,6 +20763,10 @@ var registerOpenAIGatewayRoutes = async (app, providers, tools, contexts, config
         }
         const providerapikey = resolved.apiKey;
         const languageModel = resolved.languageModel;
+        const contextWindow = await resolveContextWindow({
+          modelId: resolved.model.id,
+          exuluProvider: isLiteLLMEnabled() ? void 0 : resolved.exuluProvider
+        });
         const disabledTools = req.body.disabledTools ?? [];
         const enabledTools = await getEnabledTools(
           agent,
@@ -20188,12 +20791,50 @@ var registerOpenAIGatewayRoutes = async (app, providers, tools, contexts, config
           project?.id,
           void 0,
           languageModel,
-          agent
+          agent,
+          void 0,
+          contextWindow,
+          disabledTools
+        );
+        const gatewayAgenticEntry = enabledTools?.find((t) => t.id === "agentic_context_search");
+        const gatewayAgenticKey = gatewayAgenticEntry ? sanitizeToolName(gatewayAgenticEntry.name) : void 0;
+        const gatewayRetrievalGuard = retrievalBudgetGuard(
+          resolveRetrievalCallBudget(agent.tools),
+          gatewayAgenticKey,
+          Object.keys(convertedTools)
         );
+        const turnBudget = resolveTurnStepBudget(void 0, agent);
         const clientTools = Array.isArray(req.body.tools) ? req.body.tools : [];
         const activeTools = clientTools.length > 0 ? convertOpenAIToolsToAiSdkTools(clientTools) : convertedTools;
         const openaiMessages = req.body.messages ?? [];
         const { systemPrompt: requestSystemPrompt, coreMessages } = convertOpenAIMessagesToModelMessages(openaiMessages);
+        const gatewayBudget = deriveContextBudget(contextWindow);
+        const IMAGE_TOKEN_ALLOWANCE = 1e3;
+        let imageCount = 0;
+        const textOnlyMessages = openaiMessages.map((m) => {
+          if (!Array.isArray(m.content)) return m;
+          return {
+            ...m,
+            content: m.content.map((p) => {
+              if (p && typeof p === "object" && "image_url" in p && p.image_url) {
+                imageCount += 1;
+                return { ...p, image_url: { url: "[image]" } };
+              }
+              return p;
+            })
+          };
+        });
+        const promptTokens = estimateTokens(JSON.stringify(textOnlyMessages)) + imageCount * IMAGE_TOKEN_ALLOWANCE;
+        if (promptTokens >= gatewayBudget.blockThreshold) {
+          res.status(400).json({
+            error: {
+              message: `This request is ~${promptTokens.toLocaleString("en-US")} tokens, which exceeds the model's usable context window (${gatewayBudget.usableWindow.toLocaleString("en-US")} tokens). Reduce the conversation history.`,
+              type: "invalid_request_error",
+              code: "context_length_exceeded"
+            }
+          });
+          return;
+        }
         const agentInstructions = agent.instructions ?? "";
         const systemParts = [
           agentInstructions ? `You are an agent named: ${agent.name}
@@ -20203,7 +20844,7 @@ ${project.description}` : ""}` : "",
           requestSystemPrompt
         ].filter(Boolean);
         const systemPrompt = systemParts.join("\n\n");
-        const completionId = `chatcmpl-${(0, import_node_crypto5.randomUUID)()}`;
+        const completionId = `chatcmpl-${(0, import_node_crypto7.randomUUID)()}`;
         const created = Math.floor(Date.now() / 1e3);
         const hasTools = Object.keys(activeTools).length > 0;
         const ctx = { completionId, created, modelId };
@@ -20211,13 +20852,14 @@ ${project.description}` : ""}` : "",
           res.setHeader("Content-Type", "text/event-stream");
           res.setHeader("Cache-Control", "no-cache");
           res.setHeader("Connection", "keep-alive");
-          const result = (0, import_ai13.streamText)({
+          const result = (0, import_ai14.streamText)({
             model: languageModel,
             system: systemPrompt || void 0,
             messages: coreMessages,
             tools: hasTools ? activeTools : void 0,
             maxRetries: 2,
-            stopWhen: clientTools.length > 0 ? void 0 : [(0, import_ai13.stepCountIs)(5)],
+            prepareStep: clientTools.length > 0 ? void 0 : composePrepareSteps(contextGuard(contextWindow), gatewayRetrievalGuard, finalAnswerGuard(turnBudget)),
+            stopWhen: clientTools.length > 0 ? void 0 : [(0, import_ai14.stepCountIs)(turnBudget)],
             onError: (error) => {
               console.error("[OPENAI GATEWAY] stream error:", error);
             }
@@ -20250,13 +20892,14 @@ ${project.description}` : ""}` : "",
           const usage = await result.usage;
           await writeStatistics(agent, project, user, usage.inputTokens ?? 0, usage.outputTokens ?? 0);
         } else {
-          const { text, usage } = await (0, import_ai13.generateText)({
+          const { text, usage } = await (0, import_ai14.generateText)({
             model: languageModel,
             system: systemPrompt || void 0,
             messages: coreMessages,
             tools: hasTools ? activeTools : void 0,
             maxRetries: 2,
-            stopWhen: clientTools.length > 0 ? void 0 : [(0, import_ai13.stepCountIs)(5)]
+            prepareStep: clientTools.length > 0 ? void 0 : composePrepareSteps(contextGuard(contextWindow), gatewayRetrievalGuard, finalAnswerGuard(turnBudget)),
+            stopWhen: clientTools.length > 0 ? void 0 : [(0, import_ai14.stepCountIs)(turnBudget)]
           });
           res.json(transformCompletion(text, usage.inputTokens ?? 0, usage.outputTokens ?? 0, ctx));
           await writeStatistics(agent, project, user, usage.inputTokens ?? 0, usage.outputTokens ?? 0);
@@ -20375,7 +21018,7 @@ init_flow();
 
 // src/exulu/recall/verify.ts
 init_cjs_shims();
-var import_node_crypto6 = require("crypto");
+var import_node_crypto8 = require("crypto");
 var TOLERANCE_SECONDS = 5 * 60;
 var header = (headers, ...names) => {
   for (const name of names) {
@@ -20393,7 +21036,7 @@ var safeEqual = (a, b) => {
   const bufA = Buffer.from(a);
   const bufB = Buffer.from(b);
   if (bufA.length !== bufB.length) return false;
-  return (0, import_node_crypto6.timingSafeEqual)(bufA, bufB);
+  return (0, import_node_crypto8.timingSafeEqual)(bufA, bufB);
 };
 var verifyRecallRequest = (headers, rawBody, secret = recallVerificationSecret()) => {
   if (!secret) {
@@ -20415,7 +21058,7 @@ var verifyRecallRequest = (headers, rawBody, secret = recallVerificationSecret()
   }
   const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
   const signedContent = `${id}.${timestamp}.${body}`;
-  const expected = (0, import_node_crypto6.createHmac)("sha256", secretKey(secret)).update(signedContent).digest("base64");
+  const expected = (0, import_node_crypto8.createHmac)("sha256", secretKey(secret)).update(signedContent).digest("base64");
   const passed = signatureHeader.split(" ").some((entry) => {
     const [, sig] = entry.split(",");
     return !!sig && safeEqual(sig, expected);
@@ -20768,7 +21411,7 @@ Mood: friendly and intelligent.
       });
       return;
     }
-    const uuid = (0, import_node_crypto7.randomUUID)();
+    const uuid = (0, import_node_crypto9.randomUUID)();
     const image_url = await uploadFile(Buffer.from(image_base64, "base64"), `${uuid}.png`, config, {
       contentType: "image/png"
     }, authenticationResult.user?.id, void 0, true);
@@ -20972,6 +21615,10 @@ Mood: friendly and intelligent.
       const providerapikey = resolved.apiKey;
       const resolvedLanguageModel = resolved.languageModel;
       const resolvedModelId = resolved.model.id;
+      const contextWindow = await resolveContextWindow({
+        modelId: resolved.model.id,
+        exuluProvider: isLiteLLMEnabled() ? void 0 : resolved.exuluProvider
+      });
       if (!!headers.stream) {
         const statistics = {
           label: agent.name,
@@ -20990,27 +21637,46 @@ Mood: friendly and intelligent.
         const instructions = customInstructions ? `${agent.instructions}
 
 ${customInstructions}` : agent.instructions;
-        const result = await provider.generateStream({
-          contexts,
-          agent,
-          user,
-          instructions,
-          session: headers.session,
-          message,
-          previousMessages,
-          currentTools: enabledTools,
-          currentSkills: enabledSkills,
-          approvedTools,
-          allExuluTools: tools,
-          languageModel: resolvedLanguageModel,
-          providerapikey,
-          toolConfigs: agent.tools,
-          exuluConfig: config,
-          req
-        });
+        if (headers.session) markStreamActive(headers.session);
+        let result;
+        try {
+          result = await provider.generateStream({
+            contexts,
+            agent,
+            user,
+            instructions,
+            session: headers.session,
+            message,
+            previousMessages,
+            currentTools: enabledTools,
+            currentSkills: enabledSkills,
+            approvedTools,
+            allExuluTools: tools,
+            languageModel: resolvedLanguageModel,
+            providerapikey,
+            toolConfigs: agent.tools,
+            exuluConfig: config,
+            req,
+            contextWindow,
+            disabledTools
+          });
+        } catch (err) {
+          if (headers.session) clearStreamActive(headers.session);
+          if (err instanceof ContextCompactionRequiredError) {
+            res.status(413).send(err.message);
+            return;
+          }
+          throw err;
+        }
         result.stream.consumeStream();
         result.stream.pipeUIMessageStreamToResponse(res, {
           messageMetadata: ({ part }) => {
+            if (part.type === "finish-step") {
+              return {
+                lastStepInputTokens: part.usage.inputTokens,
+                lastStepOutputTokens: part.usage.outputTokens
+              };
+            }
             if (part.type === "finish") {
               return {
                 totalTokens: part.totalUsage.totalTokens,
@@ -21027,22 +21693,20 @@ ${customInstructions}` : agent.instructions;
           sendSources: true,
           onError: (error) => {
             console.error("[EXULU] chat response error.", error);
-            if (error == null) {
-              return "unknown error";
-            }
-            if (typeof error === "string") {
-              return error;
-            }
-            if (error instanceof Error) {
-              return error.message;
-            }
-            return JSON.stringify(error);
+            if (headers.session) clearStreamActive(headers.session);
+            let message2;
+            if (error == null) message2 = "unknown error";
+            else if (typeof error === "string") message2 = error;
+            else if (error instanceof Error) message2 = error.message;
+            else message2 = JSON.stringify(error);
+            return mapStreamErrorMessage(message2);
           },
-          generateMessageId: (0, import_ai14.createIdGenerator)({
+          generateMessageId: (0, import_ai15.createIdGenerator)({
             prefix: "msg_",
             size: 16
           }),
           onFinish: async ({ messages, isContinuation, isAborted, responseMessage }) => {
+            if (headers.session) clearStreamActive(headers.session);
             console.log(
               "[EXULU] onFinish",
               messages?.map((msg) => msg.parts?.map((part) => part.type === "text" ? part.text : null)).join("\n")
@@ -21104,33 +21768,129 @@ ${customInstructions}` : agent.instructions;
         const instructions = customInstructions ? `${agent.instructions}
 
 ${customInstructions}` : agent.instructions;
-        const response = await provider.generateSync({
-          contexts,
-          agent,
-          user,
-          req,
-          instructions,
-          session: headers.session,
-          inputMessages: [req.body.message],
-          currentTools: enabledTools,
-          currentSkills: enabledSkills,
-          allExuluTools: tools,
-          languageModel: resolvedLanguageModel,
-          providerapikey,
-          exuluConfig: config,
-          toolConfigs: agent.tools,
-          statistics: {
-            label: agent.name,
-            trigger: "agent"
-          },
-          onTokenUsage: async ({ inputTokens, outputTokens }) => {
+        let response;
+        try {
+          response = await provider.generateSync({
+            contexts,
+            agent,
+            user,
+            req,
+            instructions,
+            session: headers.session,
+            inputMessages: [req.body.message],
+            currentTools: enabledTools,
+            currentSkills: enabledSkills,
+            allExuluTools: tools,
+            languageModel: resolvedLanguageModel,
+            providerapikey,
+            exuluConfig: config,
+            toolConfigs: agent.tools,
+            contextWindow,
+            disabledTools,
+            statistics: {
+              label: agent.name,
+              trigger: "agent"
+            },
+            onTokenUsage: async ({ inputTokens, outputTokens }) => {
+            }
+          });
+        } catch (err) {
+          if (err instanceof ContextCompactionRequiredError) {
+            res.status(413).send(err.message);
+            return;
           }
-        });
+          throw err;
+        }
         res.status(200).json(response);
         return;
       }
     });
   };
+  const registerAgentCompactRoute = (slug) => {
+    app.post(slug + "/:instance", async (req, res) => {
+      const instance2 = req.params.instance;
+      if (!instance2) {
+        res.status(400).json({ message: "Missing instance in request." });
+        return;
+      }
+      const sessionID = req.headers["session"] || null;
+      if (!sessionID) {
+        res.status(400).json({ message: "Missing session header." });
+        return;
+      }
+      const agent = await exuluApp.get().agent(instance2);
+      if (!agent) {
+        res.status(404).json({ message: "Agent with id " + instance2 + " not found." });
+        return;
+      }
+      const authenticationResult = await requestValidators.authenticate(req);
+      if (!authenticationResult.user?.id) {
+        res.status(authenticationResult.code || 401).json({ detail: `${authenticationResult.message}` });
+        return;
+      }
+      const user = authenticationResult.user;
+      const hasAccessToAgent = await checkRecordAccess(agent, "read", user);
+      if (!hasAccessToAgent) {
+        res.status(401).json({ message: "You don't have access to this agent." });
+        return;
+      }
+      const { db: db2 } = await postgresClient();
+      const sessionRow = await db2.from("agent_sessions").where({ id: sessionID }).first();
+      if (!sessionRow) {
+        res.status(404).json({ message: "Session not found for session ID: " + sessionID });
+        return;
+      }
+      const hasAccessToSession = await checkRecordAccess(sessionRow, "write", user);
+      if (!hasAccessToSession) {
+        res.status(401).json({ message: "You don't have access to this session." });
+        return;
+      }
+      if (isStreamActive(sessionID)) {
+        res.status(409).json({ message: "A response is still streaming for this session \u2014 try again when it finishes." });
+        return;
+      }
+      const overrideModelId = req.headers["x-exulu-model-override"];
+      const modelId = overrideModelId ?? agent.model;
+      if (!modelId) {
+        res.status(400).json({ message: `Agent ${agent.name} (${agent.id}) has no model configured.` });
+        return;
+      }
+      let resolved;
+      try {
+        resolved = await resolveModel({ modelId, user, providers, agent });
+      } catch (err) {
+        if (err instanceof ResolveModelError) {
+          const status = err.code === "MODEL_FORBIDDEN" ? 403 : 400;
+          res.status(status).json({ message: err.message, code: err.code });
+          return;
+        }
+        throw err;
+      }
+      const contextWindow = await resolveContextWindow({
+        modelId: resolved.model.id,
+        exuluProvider: isLiteLLMEnabled() ? void 0 : resolved.exuluProvider
+      });
+      const steer = typeof req.body?.steer === "string" ? req.body.steer : void 0;
+      try {
+        const result = await compactSession({
+          sessionID,
+          user,
+          languageModel: resolved.languageModel,
+          contextWindow,
+          steer,
+          modelId: resolved.model.id
+        });
+        res.json(result);
+      } catch (err) {
+        if (err instanceof CompactionInsufficientError) {
+          res.status(422).send(err.message);
+          return;
+        }
+        console.error("[EXULU] compactSession failed.", err);
+        res.status(500).json({ message: err instanceof Error ? err.message : "Compaction failed." });
+      }
+    });
+  };
   providers.forEach((provider) => {
     const slug = provider.slug;
     if (!slug) return;
@@ -21139,6 +21899,14 @@ ${customInstructions}` : agent.instructions;
   if (isLiteLLMEnabled() && providers.length > 0) {
     registerAgentRunRoute("/agents/litellm/run", providers[0]);
   }
+  providers.forEach((provider) => {
+    const slug = provider.slug;
+    if (!slug) return;
+    registerAgentCompactRoute(slug.replace(/\/run$/, "/compact"));
+  });
+  if (isLiteLLMEnabled() && providers.length > 0) {
+    registerAgentCompactRoute("/agents/litellm/compact");
+  }
   app.post("/agents/suggestions/:agentId", async (req, res) => {
     const agentId = req.params.agentId;
     if (!agentId) {
@@ -21490,7 +22258,7 @@ ${customInstructions}` : agent.instructions;
     const keys = [];
     const revisedPrompts = [];
     for (const img of images) {
-      const filename = `${(0, import_node_crypto7.randomUUID)()}.${img.extension}`;
+      const filename = `${(0, import_node_crypto9.randomUUID)()}.${img.extension}`;
       const key = `sessions/${sessionId}/images/${toolCallId}/${filename}`;
       const fullKey = await uploadFile(
         img.buffer,
@@ -21778,7 +22546,7 @@ ${style.markdown}` : params.prompt;
       (d) => `- ${d.presignedUrl} (prompt: "${d.prompt}", model: ${d.model}${d.styleName ? `, style: ${d.styleName}` : ""})`
     );
     const messageText = "The user generated and selected the following image(s) in this chat:\n" + lines.join("\n");
-    const messageId = (0, import_node_crypto7.randomUUID)();
+    const messageId = (0, import_node_crypto9.randomUUID)();
     const uiMessage = {
       id: messageId,
       role: "system",
@@ -22706,7 +23474,7 @@ ${style.markdown}` : params.prompt;
       res.status(404).json({ detail: "Skill not found." });
       return;
     }
-    const stagingKey = `user_${authResult.user.id}/skills/_staging/${(0, import_node_crypto7.randomUUID)()}${extension}`;
+    const stagingKey = `user_${authResult.user.id}/skills/_staging/${(0, import_node_crypto9.randomUUID)()}${extension}`;
     const fullKey = config.fileUploads?.s3prefix ? `${config.fileUploads.s3prefix.replace(/\/$/, "")}/${stagingKey}` : stagingKey;
     const uploadUrl = await getS3SignedUploadUrl(fullKey, contentType, config);
     res.json({ uploadUrl, stagingKey });
@@ -23738,7 +24506,7 @@ function buildUnifiedDiff(fromLines, toLines, fromLabel, toLabel) {
 // src/mcp/index.ts
 init_cjs_shims();
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_node_crypto8 = require("crypto");
+var import_node_crypto10 = require("crypto");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_types3 = require("@modelcontextprotocol/sdk/types.js");
 init_sanitize_tool_name();
@@ -23850,7 +24618,7 @@ var ExuluMCP = class {
             throw new Error("Tool not found in converted tools array.");
           }
           const iterator = await convertedTool.execute(inputs, {
-            toolCallId: tool4.id + "_" + (0, import_node_crypto8.randomUUID)(),
+            toolCallId: tool4.id + "_" + (0, import_node_crypto10.randomUUID)(),
             messages: []
           });
           let result;
@@ -24042,7 +24810,7 @@ var ExuluMCP = class {
         transport = this.transports[sessionId];
       } else if (!sessionId && (0, import_types3.isInitializeRequest)(req.body)) {
         transport = new import_streamableHttp.StreamableHTTPServerTransport({
-          sessionIdGenerator: () => (0, import_node_crypto8.randomUUID)(),
+          sessionIdGenerator: () => (0, import_node_crypto10.randomUUID)(),
           onsessioninitialized: (sessionId2) => {
             this.transports[sessionId2] = transport;
           }
@@ -24996,7 +25764,7 @@ init_cjs_shims();
 
 // src/exulu/evals.ts
 init_cjs_shims();
-var import_ai15 = require("ai");
+var import_ai16 = require("ai");
 init_entitlements();
 var ExuluEval = class {
   id;
@@ -25037,7 +25805,7 @@ var ExuluEval = class {
 init_resolve_model();
 init_singleton();
 var import_zod15 = require("zod");
-var import_ai16 = require("ai");
+var import_ai17 = require("ai");
 var llmAsJudgeEval = () => {
   if (process.env.REDIS_HOST?.length && process.env.REDIS_PORT?.length) {
     return new ExuluEval({
@@ -25082,13 +25850,13 @@ var llmAsJudgeEval = () => {
           rbacBypass: true
         });
         console.log("[EXULU] prompt", prompt);
-        const { output } = await (0, import_ai16.generateText)({
+        const { output } = await (0, import_ai17.generateText)({
           temperature: 0,
           model: resolved.languageModel,
           system: "",
           prompt,
           maxRetries: 2,
-          output: import_ai16.Output.object({
+          output: import_ai17.Output.object({
             schema: import_zod15.z.object({
               score: import_zod15.z.number().min(0).max(100).describe("The score between 0 and 100.")
             })
@@ -25522,7 +26290,7 @@ var import_zod17 = __toESM(require("zod"), 1);
 init_tool();
 init_check_record_access();
 init_client();
-var import_node_crypto9 = require("crypto");
+var import_node_crypto11 = require("crypto");
 var AnswerOptionSchema = import_zod17.default.object({
   id: import_zod17.default.string().describe("Unique identifier for the answer option"),
   text: import_zod17.default.string().describe("The text of the answer option")
@@ -25576,15 +26344,15 @@ var QuestionAskTool = new ExuluTool({
       throw new Error("You don't have access to this session " + session.id + ".");
     }
     const answerOptionsWithIds = answerOptions.map((text) => ({
-      id: (0, import_node_crypto9.randomUUID)(),
+      id: (0, import_node_crypto11.randomUUID)(),
       text
     }));
     answerOptionsWithIds.push({
-      id: (0, import_node_crypto9.randomUUID)(),
+      id: (0, import_node_crypto11.randomUUID)(),
       text: "None of the above..."
     });
     const newQuestion = {
-      id: (0, import_node_crypto9.randomUUID)(),
+      id: (0, import_node_crypto11.randomUUID)(),
       question,
       answerOptions: answerOptionsWithIds,
       status: "pending"
@@ -28618,7 +29386,7 @@ var MarkdownChunker = class {
 init_cjs_shims();
 var fs4 = __toESM(require("fs"), 1);
 var path = __toESM(require("path"), 1);
-var import_ai17 = require("ai");
+var import_ai18 = require("ai");
 var import_zod22 = require("zod");
 var import_p_limit = __toESM(require("p-limit"), 1);
 var import_crypto2 = require("crypto");
@@ -29083,9 +29851,9 @@ If the page contains a flow-chart, schematic, technical drawing or control board
 
 ### 7. Only populate \`corrected_text\` when \`needs_correction\` is true. If the OCR output is accurate, return \`needs_correction: false\` and \`corrected_content: null\`.
 `;
-  const result = await (0, import_ai17.generateText)({
+  const result = await (0, import_ai18.generateText)({
     model,
-    output: import_ai17.Output.object({
+    output: import_ai18.Output.object({
       schema: import_zod22.z.object({
         needs_correction: import_zod22.z.boolean(),
         corrected_text: import_zod22.z.string().nullable(),