@exulu/backend 1.68.0 → 1.69.0

package/dist/index.cjs

@@ -160,9 +160,9 @@ async function postgresClient() {
           // Log pool events to help debug connection issues
           afterCreate: (conn, done) => {
             console.log("[EXULU] New database connection created");
-            conn.query("SET statement_timeout = 1800000", (err) => {
+            conn.query("SET statement_timeout = 1800000; SET hnsw.ef_search = 20", (err) => {
               if (err) {
-                console.error("[EXULU] Error setting statement_timeout:", err);
+                console.error("[EXULU] Error setting connection parameters:", err);
               }
               done(err, conn);
             });
@@ -1351,6 +1351,18 @@ var init_sanitize_name = __esm({
   }
 });
 
+// src/exulu/table-names.ts
+var getTableName, getChunksTableName;
+var init_table_names = __esm({
+  "src/exulu/table-names.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_sanitize_name();
+    getTableName = (id) => sanitizeName(id) + "_items";
+    getChunksTableName = (id) => sanitizeName(id) + "_chunks";
+  }
+});
+
 // ee/tokenizer.ts
 var import_lite, import_load, import_registry, import_model_to_encoding, ExuluTokenizer;
 var init_tokenizer = __esm({
@@ -2052,7 +2064,7 @@ var init_chunker = __esm({
 });
 
 // src/exulu/litellm/supervisor.ts
-var import_node_child_process, import_node_fs3, import_node_path2, LITELLM_UI_PATH, MAX_CRASHES, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, READY_TIMEOUT_MS, WAIT_TIMEOUT_MS, READY_POLL_INTERVAL_MS, SHUTDOWN_GRACE_MS, internal, isLiteLLMEnabled, resolveConfig, log, pollHealth, spawnLiteLLM, supervise, _packageRoot, _clientMode, setLiteLLMPackageRoot, enableLiteLLMClientMode, startLiteLLMSupervisor, waitForLiteLLMReady, stopLiteLLM, shutdownHandlersRegistered, registerShutdownHandlers, getSupervisorState;
+var import_node_child_process, import_node_fs3, import_node_path2, LITELLM_UI_PATH, MAX_CRASHES, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, READY_TIMEOUT_MS, WAIT_TIMEOUT_MS, READY_POLL_INTERVAL_MS, SHUTDOWN_GRACE_MS, internal, isLiteLLMEnabled, resolveConfig, log2, pollHealth, spawnLiteLLM, supervise, _packageRoot, _clientMode, setLiteLLMPackageRoot, enableLiteLLMClientMode, startLiteLLMSupervisor, waitForLiteLLMReady, stopLiteLLM, shutdownHandlersRegistered, registerShutdownHandlers, getSupervisorState;
 var init_supervisor = __esm({
   "src/exulu/litellm/supervisor.ts"() {
     "use strict";
@@ -2087,7 +2099,7 @@ var init_supervisor = __esm({
       const litellmBin = (0, import_node_path2.resolve)(venvBin, "litellm");
       return { host, port, masterKey, configPath, venvBin, venvPython, litellmBin };
     };
-    log = (line) => console.log(`[EXULU-LITELLM] ${line}`);
+    log2 = (line) => console.log(`[EXULU-LITELLM] ${line}`);
     pollHealth = async (host, port) => {
       const url = `http://${host}:${port}/health/liveliness`;
       const deadline = Date.now() + READY_TIMEOUT_MS;
@@ -2104,7 +2116,7 @@ var init_supervisor = __esm({
       );
     };
     spawnLiteLLM = (cfg) => {
-      log(
+      log2(
         `Spawning LiteLLM: ${cfg.litellmBin} --config ${cfg.configPath} --port ${cfg.port} --host ${cfg.host}`
       );
       const { DEBUG: _debug, ...rest } = process.env;
@@ -2131,10 +2143,10 @@ var init_supervisor = __esm({
         }
       );
       child.stdout?.on("data", (chunk) => {
-        chunk.toString().split("\n").filter((l) => l.length > 0).forEach((l) => log(l));
+        chunk.toString().split("\n").filter((l) => l.length > 0).forEach((l) => log2(l));
       });
       child.stderr?.on("data", (chunk) => {
-        chunk.toString().split("\n").filter((l) => l.length > 0).forEach((l) => log(`stderr: ${l}`));
+        chunk.toString().split("\n").filter((l) => l.length > 0).forEach((l) => log2(`stderr: ${l}`));
       });
       return child;
     };
@@ -2151,7 +2163,7 @@ var init_supervisor = __esm({
             exitPromise.then((code2) => ({ exited: code2 }))
           ]);
         } catch (err) {
-          log(`Readiness probe failed: ${err.message}`);
+          log2(`Readiness probe failed: ${err.message}`);
           try {
             internal.child?.kill("SIGTERM");
           } catch {
@@ -2161,22 +2173,22 @@ var init_supervisor = __esm({
           internal.state = "ready";
           internal.crashCount = 0;
           internal.backoffMs = INITIAL_BACKOFF_MS;
-          log("LiteLLM is ready.");
+          log2("LiteLLM is ready.");
         }
         const code = await exitPromise;
         internal.state = "respawning";
         internal.child = void 0;
         if (internal.shutdownRequested) {
-          log("Child exited during shutdown; supervisor stopping.");
+          log2("Child exited during shutdown; supervisor stopping.");
           internal.state = "stopped";
           return;
         }
         internal.crashCount += 1;
-        log(
+        log2(
           `LiteLLM exited (code=${code}). Crash ${internal.crashCount}/${MAX_CRASHES}. Respawning in ${internal.backoffMs}ms.`
         );
         if (internal.crashCount >= MAX_CRASHES) {
-          log(
+          log2(
             "LiteLLM keeps crashing \u2014 fix the config and restart Exulu. Giving up on respawn."
           );
           internal.state = "given_up";
@@ -2212,14 +2224,14 @@ var init_supervisor = __esm({
       }
       const cfg = resolveConfig(packageRoot);
       if (!(0, import_node_fs3.existsSync)(cfg.configPath)) {
-        log(
+        log2(
           `LiteLLM config not found at ${cfg.configPath}. Copy ee/python/.litellm/config.yaml.example to that path, edit it, and restart Exulu. LiteLLM will NOT be started until then.`
         );
         internal.state = "given_up";
         return;
       }
       if (!(0, import_node_fs3.existsSync)(cfg.litellmBin)) {
-        log(
+        log2(
           `LiteLLM binary not found at ${cfg.litellmBin}. The Python venv may not be set up. Run setupPythonEnvironment() from @exulu/backend, then restart.`
         );
         internal.state = "given_up";
@@ -2737,11 +2749,20 @@ function durationToDays(duration) {
 }
 function windowStartYmd(reset_at, duration) {
   const days = durationToDays(duration);
+  const windowMs = days * DAY_MS;
+  const now = Date.now();
   const reset = reset_at ? new Date(reset_at) : null;
-  const periodStart = reset && !Number.isNaN(reset.getTime()) ? new Date(reset.getTime() - days * DAY_MS) : null;
-  const trailingStart = new Date(Date.now() - days * DAY_MS);
-  const chosen = periodStart && periodStart > trailingStart ? periodStart : trailingStart;
-  return ymd(chosen);
+  const resetMs = reset && !Number.isNaN(reset.getTime()) ? reset.getTime() : null;
+  const trailingStart = new Date(now - windowMs);
+  if (resetMs !== null) {
+    if (resetMs > now) {
+      const periodStart = new Date(resetMs - windowMs);
+      return ymd(periodStart > trailingStart ? periodStart : trailingStart);
+    } else {
+      return ymd(reset > trailingStart ? reset : trailingStart);
+    }
+  }
+  return ymd(trailingStart);
 }
 async function enrichSpendFromActivity(map) {
   const names = Object.keys(map);
@@ -2752,7 +2773,10 @@ async function enrichSpendFromActivity(map) {
     windows[name] = windowStartYmd(ti.budget_reset_at, ti.budget_duration);
   }
   try {
-    const spendByTag = await getTagSpendByWindow(windows, ymd(/* @__PURE__ */ new Date()));
+    const spendByTag = await getTagSpendByWindow(
+      windows,
+      ymd(new Date(Date.now() + DAY_MS))
+    );
     for (const name of names) {
       const spend = spendByTag[name];
       if (typeof spend === "number" && Number.isFinite(spend)) {
@@ -2876,6 +2900,7 @@ async function getUserBudgetView(userId) {
       readCache.set(tag, { expiry: Date.now() + READ_TTL_MS, view: null });
       return null;
     }
+    await provisionDefaultUserBudget(userId);
     const info = await tagInfo([tag]);
     const ti = info[tag];
     if (ti?.max_budget != null) {
@@ -3847,7 +3872,7 @@ var init_entitlements = __esm({
 });
 
 // src/postgres/core-schema.ts
-var agentMessagesSchema, agentSessionsSchema, skillsSchema, variablesSchema, projectsSchema, agentsSchema, modelsSchema, usersSchema, platformConfigurationsSchema, entityTypeSettingsSchema, promptLibrarySchema, promptFavoritesSchema, transcriptionJobsSchema, imageGenerationsSchema, oauthTokensSchema, contextPresetsSchema, addCoreFields, coreSchemas;
+var agentMessagesSchema, agentSessionsSchema, skillsSchema, variablesSchema, projectsSchema, agentsSchema, modelsSchema, usersSchema, platformConfigurationsSchema, entityTypeSettingsSchema, promptLibrarySchema, promptFavoritesSchema, transcriptionJobsSchema, imageGenerationsSchema, oauthTokensSchema, sharedArtifactsSchema, contextPresetsSchema, addCoreFields, coreSchemas;
 var init_core_schema = __esm({
   "src/postgres/core-schema.ts"() {
     "use strict";
@@ -4112,6 +4137,11 @@ var init_core_schema = __esm({
         {
           name: "animation_responding",
           type: "text"
+        },
+        {
+          name: "sandbox_enabled",
+          type: "boolean",
+          default: false
         }
       ]
     };
@@ -4517,6 +4547,26 @@ var init_core_schema = __esm({
         // null = non-expiring
       ]
     };
+    sharedArtifactsSchema = {
+      type: "shared_artifacts",
+      name: {
+        plural: "shared_artifacts",
+        singular: "shared_artifact"
+      },
+      // RBAC drives the "regular" auth_mode: rights_mode + the rbac table scope
+      // who may view. public/password modes ignore rights_mode.
+      RBAC: true,
+      fields: [
+        { name: "name", type: "text", index: true, unique: true, required: true },
+        { name: "s3key", type: "text", required: true },
+        { name: "auth_mode", type: "text", default: "regular" },
+        { name: "password_hash", type: "text", required: false },
+        // bcrypt; password mode only
+        { name: "expires_at", type: "date", required: false },
+        // null = no expiry
+        { name: "content_type", type: "text", required: false }
+      ]
+    };
     contextPresetsSchema = {
       type: "context_presets",
       name: {
@@ -4609,6 +4659,7 @@ var init_core_schema = __esm({
           promptFavoritesSchema: () => addCoreFields(promptFavoritesSchema),
           contextPresetsSchema: () => addCoreFields(contextPresetsSchema),
           oauthTokensSchema: () => addCoreFields(oauthTokensSchema),
+          sharedArtifactsSchema: () => addCoreFields(sharedArtifactsSchema),
           transcriptionJobsSchema: () => addCoreFields(transcriptionJobsSchema),
           imageGenerationsSchema: () => addCoreFields(imageGenerationsSchema)
         };
@@ -5105,7 +5156,12 @@ var init_resolve_model = __esm({
         // supports — including Vertex Gemini, which translates it into
         // responseSchema/responseMimeType — so enabling this matches the actual
         // proxy contract.
-        supportsStructuredOutputs: true
+        supportsStructuredOutputs: true,
+        // Request token usage on STREAMED responses. Without this the openai-compatible
+        // provider omits `stream_options: { include_usage: true }`, so LiteLLM returns no
+        // usage for streaming calls — which zeroes out the per-request token metrics and
+        // the message-footer token count (both read the AI SDK `totalUsage`/finish-part usage).
+        includeUsage: true
       });
     };
   }
@@ -5768,7 +5824,8 @@ var init_vector_search = __esm({
       trigger,
       cutoffs,
       expand,
-      entityFilter
+      entityFilter,
+      queryEmbedding
     }) => {
       const table = convertContextToTableDefinition(context);
       console.log("[EXULU] Called vector search.", {
@@ -5850,36 +5907,53 @@ var init_vector_search = __esm({
       let vector = [];
       let vectorStr = "";
       let vectorExpr = "";
+      const _tBody = Date.now();
+      let _preMs = 0, _statMs = 0, _resolveMs = 0, _embedMs = 0;
+      let _embedSource = "none";
       if (query) {
+        const _tp = Date.now();
         const { processed: stemmedQuery } = preprocessQuery(query, {
           enableStemming: true,
           detectLanguage: true
         });
+        _preMs = Date.now() - _tp;
         console.log("[EXULU] Stemmed query:", stemmedQuery);
         if (stemmedQuery) {
           query = stemmedQuery;
         }
-        await updateStatistic({
-          name: "count",
-          label: table.name.singular,
-          type: STATISTICS_TYPE_ENUM.EMBEDDER_GENERATE,
-          trigger,
-          count: 1,
-          user: user?.id,
-          role
-        });
-        const resolved = await resolveEmbedder({
-          model: embedder.model,
-          contextId: context.id,
-          contextName: context.name,
-          user,
-          roleId: role
-        });
-        const [queryVector] = await resolved.embed([query], { inputType: "query" });
-        if (!queryVector?.length) {
-          throw new Error("No vector generated for query.");
+        if (queryEmbedding && queryEmbedding.length) {
+          vector = queryEmbedding;
+          _embedSource = "reused";
+        } else {
+          const _ts = Date.now();
+          await updateStatistic({
+            name: "count",
+            label: table.name.singular,
+            type: STATISTICS_TYPE_ENUM.EMBEDDER_GENERATE,
+            trigger,
+            count: 1,
+            user: user?.id,
+            role
+          });
+          _statMs = Date.now() - _ts;
+          const _tr = Date.now();
+          const resolved = await resolveEmbedder({
+            model: embedder.model,
+            contextId: context.id,
+            contextName: context.name,
+            user,
+            roleId: role
+          });
+          _resolveMs = Date.now() - _tr;
+          const _te = Date.now();
+          const [queryVector] = await resolved.embed([query], { inputType: "query" });
+          _embedMs = Date.now() - _te;
+          if (!queryVector?.length) {
+            throw new Error("No vector generated for query.");
+          }
+          vector = queryVector;
+          _embedSource = "computed";
         }
-        vector = queryVector;
         vectorStr = `ARRAY[${vector.join(",")}]`;
         vectorExpr = `${vectorStr}::vector`;
       }
@@ -5906,6 +5980,7 @@ var init_vector_search = __esm({
       const languages = configuration.languages?.length ? configuration.languages : ["english"];
       console.log("[EXULU] Vector search params:", { method, query, cutoffs, languages });
       let resultChunks = [];
+      const _tSql = Date.now();
       switch (method) {
         case "tsvector":
           chunksQuery.limit(limit * 2);
@@ -6019,6 +6094,11 @@ var init_vector_search = __esm({
           ]).orderByRaw("hybrid_score DESC").limit(Math.min(matchCount, 250));
           resultChunks = await hybridQuery;
       }
+      if (process.env.EXULU_VS_TIMING) {
+        console.log(
+          `[EXULU-VS] ctx=${context.id} method=${method} embed=${_embedSource} pre=${_preMs}ms stat=${_statMs}ms resolve=${_resolveMs}ms embedApi=${_embedMs}ms sql=${Date.now() - _tSql}ms total=${Date.now() - _tBody}ms`
+        );
+      }
       console.log("[EXULU] Vector search chunk results:", resultChunks?.length);
       let results = resultChunks.map((chunk) => ({
         chunk_content: chunk.content,
@@ -6480,13 +6560,14 @@ var init_decorator = __esm({
 });
 
 // src/exulu/context.ts
-var import_knex5, getTableName, getChunksTableName, ExuluContext2;
+var import_knex5, ExuluContext2;
 var init_context = __esm({
   "src/exulu/context.ts"() {
     "use strict";
     init_cjs_shims();
     init_storage();
     init_sanitize_name();
+    init_table_names();
     import_knex5 = __toESM(require("pgvector/knex"), 1);
     init_chunker();
     init_resolve_embedder();
@@ -6497,15 +6578,10 @@ var init_context = __esm({
     init_vector_search();
     init_convert_context_to_table_definition();
     init_apply_filters();
+    init_access_control();
     init_map_types();
     init_decorator();
     init_entities();
-    getTableName = (id) => {
-      return sanitizeName(id) + "_items";
-    };
-    getChunksTableName = (id) => {
-      return sanitizeName(id) + "_chunks";
-    };
     ExuluContext2 = 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.
@@ -6999,12 +7075,18 @@ var init_context = __esm({
       };
       getItems = async ({
         filters,
-        fields
+        fields,
+        user,
+        role
       }) => {
         const { db: db2 } = await postgresClient();
-        let query = db2.from(getTableName(this.id)).select(fields || "*");
         const tableDefinition = convertContextToTableDefinition(this);
+        let query = db2.from(getTableName(this.id)).select(fields || "*");
         query = applyFilters(query, filters || [], tableDefinition);
+        if (user) {
+          const acUser = role && (!user.role || user.role.id !== role) ? { ...user, role: { ...user.role ?? {}, id: role } } : user;
+          query = applyAccessControl(tableDefinition, query, acUser);
+        }
         const items = await query;
         return items;
       };
@@ -7365,11 +7447,9 @@ async function resolveReranker(input) {
         rerank_score: r.relevance_score ?? 0
       }));
       reranked.sort((a, b) => b.rerank_score - a.rerank_score);
-      import_fs.default.writeFileSync("reranked.json", JSON.stringify(reranked, null, 2));
       return reranked;
     } catch (err) {
       console.error("[EXULU] Error reranking:", err);
-      import_fs.default.writeFileSync("reranked.json", JSON.stringify(err, null, 2));
       return [];
     }
   };
@@ -7383,7 +7463,7 @@ var init_resolve_reranker = __esm({
     init_supervisor();
     init_budget_service();
     init_tags();
-    import_fs = __toESM(require("fs"), 1);
+    import_fs = require("fs");
     ResolveRerankerError = class extends Error {
       constructor(code, message) {
         super(message);
@@ -7984,9 +8064,21 @@ var init_memory_tool = __esm({
           case "longText":
           case "shortText":
           case "code":
-          case "enum":
             fields[field.name] = import_zod4.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(
+                (v) => typeof v === "string" ? v.toUpperCase() : v,
+                import_zod4.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");
+            }
+            break;
           case "json":
             fields[field.name] = import_zod4.z.string({}).describe(
               "The " + field.name + " of the item to create, it should be a valid JSON string."
@@ -8012,6 +8104,9 @@ var init_memory_tool = __esm({
             break;
         }
       }
+      fields["visibility"] = import_zod4.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";
       return new ExuluTool({
         id: toolName,
@@ -8021,14 +8116,36 @@ var init_memory_tool = __esm({
         type: "function",
         inputSchema: import_zod4.z.object(fields),
         config: [],
-        execute: async ({ name, description, surroundingContext, mode, information, exuluConfig, user }) => {
+        execute: async (params) => {
+          const { name, description, surroundingContext, information, visibility, exuluConfig, user } = params;
           let result = { result: "" };
+          if (!visibility) {
+            return {
+              result: `Before saving this memory, ask the user whether it should be PRIVATE (visible only to them) or PUBLIC (shared with the team), then call \`${toolName}\` again with \`visibility\` set.`
+            };
+          }
           try {
+            const extraFields = {};
+            for (const field of context.fields ?? []) {
+              if (field.type === "enum" && field.enumValues && field.enumValues.length > 0) {
+                const raw = params[field.name];
+                if (raw !== void 0 && raw !== null && raw !== "") {
+                  const rawStr = String(raw);
+                  const canonical = field.enumValues.find(
+                    (v) => v.toUpperCase() === rawStr.toUpperCase()
+                  );
+                  if (canonical !== void 0) {
+                    extraFields[field.name] = canonical;
+                  }
+                }
+              }
+            }
             const newItem = {
               name,
               description: "Description: " + description + "\n\nSurrounding Context: " + surroundingContext,
               information: "Information: " + information,
-              rights_mode: "public"
+              rights_mode: visibility === "private" ? "private" : "public",
+              ...extraFields
             };
             const { item: createdItem, job: createdJob } = await context.createItem(
               newItem,
@@ -8841,7 +8958,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
         contexts = [];
       }
       let sharedSessionSandbox;
-      if (sessionID && exuluConfig) {
+      if (sessionID && exuluConfig && agent?.sandbox_enabled === true) {
         try {
           sharedSessionSandbox = await createSessionSandbox(
             sessionID,
@@ -10922,11 +11039,13 @@ __export(index_exports, {
   ExuluProvider: () => ExuluProvider,
   ExuluPython: () => ExuluPython,
   ExuluQueues: () => queues,
+  ExuluReadApi: () => ExuluReadApi,
   ExuluReranker: () => ExuluReranker,
   ExuluTool: () => ExuluTool,
   ExuluTrajectoryRegistry: () => trajectoryRegistry,
   ExuluVariables: () => ExuluVariables,
-  defaultChunker: () => defaultChunker
+  defaultChunker: () => defaultChunker,
+  postgresClient: () => postgresClient
 });
 module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
@@ -10945,6 +11064,73 @@ var redisServer = {
   username: process.env.REDIS_USER || ""
 };
 
+// ee/queues/redis-startup.ts
+init_cjs_shims();
+var REDIS_STARTUP_TIMEOUT_MS = 6e4;
+var WATCHDOG_INTERVAL_MS = 1e4;
+var ERROR_LOG_THROTTLE_MS = 3e4;
+var log = (line) => console.log(`[EXULU-REDIS] ${line}`);
+var warn = (line) => console.warn(`[EXULU-REDIS] ${line}`);
+var errorLog = (line) => console.error(`[EXULU-REDIS] ${line}`);
+var redisAddress = () => `${redisServer.host || "(unset)"}:${redisServer.port || "(unset)"}`;
+var describeError = (e) => {
+  const any = e;
+  const head = any?.message ? String(any.message).split("\n")[0] : void 0;
+  if (any?.code) return head && head !== any.code ? `${any.code} (${head})` : `${any.code}`;
+  return head ?? String(e);
+};
+function logRedisErrors(source, label) {
+  let count = 0;
+  let lastLoggedAt = 0;
+  source.on("error", (err) => {
+    count += 1;
+    const now = Date.now();
+    if (count === 1 || now - lastLoggedAt >= ERROR_LOG_THROTTLE_MS) {
+      errorLog(`${label} connection error (${redisAddress()}): ${describeError(err)}${count > 1 ? ` (x${count})` : ""}`);
+      lastLoggedAt = now;
+    }
+  });
+}
+async function guardRedisStartup(label, run, source) {
+  const addr = redisAddress();
+  log(`Connecting to Redis (${addr}) for ${label}\u2026`);
+  const startedAt = Date.now();
+  let lastError;
+  const onError = (err) => {
+    lastError = err;
+  };
+  source?.on("error", onError);
+  const watchdog = setInterval(() => {
+    const secs = Math.round((Date.now() - startedAt) / 1e3);
+    warn(
+      `\u26A0 Still waiting for Redis at ${addr} after ${secs}s \u2014 ${label} startup is blocked. Is Redis running? (aborting at ${REDIS_STARTUP_TIMEOUT_MS / 1e3}s)`
+    );
+  }, WATCHDOG_INTERVAL_MS);
+  watchdog.unref?.();
+  let timer2;
+  const timeout = new Promise((_resolve, reject) => {
+    timer2 = setTimeout(() => {
+      reject(
+        new Error(
+          `[EXULU-REDIS] Redis unreachable at ${addr} after ${REDIS_STARTUP_TIMEOUT_MS / 1e3}s \u2014 aborting ${label} startup. Last error: ${lastError ? describeError(lastError) : "none surfaced"}. Check REDIS_HOST/REDIS_PORT and that a Redis server is reachable at ${addr}.`
+        )
+      );
+    }, REDIS_STARTUP_TIMEOUT_MS);
+  });
+  const runPromise = Promise.resolve().then(run);
+  runPromise.catch(() => {
+  });
+  try {
+    const result = await Promise.race([runPromise, timeout]);
+    log(`Redis ready; ${label} initialized (${addr}, ${((Date.now() - startedAt) / 1e3).toFixed(1)}s).`);
+    return result;
+  } finally {
+    clearInterval(watchdog);
+    if (timer2) clearTimeout(timer2);
+    source?.off?.("error", onError);
+  }
+}
+
 // src/redis/client.ts
 var client = {};
 async function redisClient() {
@@ -10962,9 +11148,11 @@ async function redisClient() {
       client["exulu"] = (0, import_redis.createClient)({
         url
       });
-      await client["exulu"].connect();
+      logRedisErrors(client["exulu"], "client");
+      await guardRedisStartup("client", () => client["exulu"].connect().then(() => void 0), client["exulu"]);
     } catch (error) {
       console.error(`[EXULU] error connecting to redis:`, error);
+      delete client["exulu"];
       return { client: null };
     }
   }
@@ -10989,7 +11177,8 @@ init_client();
 init_auth();
 var requestValidators = {
   authenticate: async (req) => {
-    const apikey = req.headers["exulu-api-key"] || null;
+    const rawApiKey = req.headers["exulu-api-key"] || req.headers["x-api-key"];
+    const apikey = rawApiKey?.replace(/^Bearer\s+/i, "") || null;
     const { db: db2 } = await postgresClient();
     let authtoken = null;
     if (typeof apikey !== "string") {
@@ -11082,7 +11271,7 @@ var requestValidators = {
 init_statistics();
 init_client();
 var import_express5 = __toESM(require("express"), 1);
-var import_server4 = require("@apollo/server");
+var import_server5 = require("@apollo/server");
 var import_cors = __toESM(require("cors"), 1);
 var import_reflect_metadata = require("reflect-metadata");
 
@@ -11275,6 +11464,14 @@ var ExuluQueues = class {
         },
         telemetry: new import_bullmq_otel.BullMQOtel("simple-guide")
       });
+      logRedisErrors(newQueue, `queue "${name}"`);
+      try {
+        await guardRedisStartup(`queue "${name}"`, () => newQueue.waitUntilReady(), newQueue);
+      } catch (err) {
+        void newQueue.close().catch(() => {
+        });
+        throw err;
+      }
       await newQueue.setGlobalConcurrency(queueConcurrency);
       this.queues.push({
         queue: newQueue,
@@ -13436,6 +13633,8 @@ var createWorkers = async (providers, queues2, config, contexts, evals, tools, t
       },
       maxRetriesPerRequest: null
     });
+    logRedisErrors(redisConnection, "worker");
+    await guardRedisStartup("workers", () => redisConnection.ping().then(() => void 0), redisConnection);
   }
   const workers = queues2.map((queue) => {
     console.log(`[EXULU] creating worker for queue ${queue.queue.name}.`);
@@ -14615,7 +14814,7 @@ var renderTranscript = (segments, speakers) => {
 
 // src/exulu/transcription/service.ts
 var TABLE2 = "transcription_jobs";
-var log2 = (msg) => console.log(`[EXULU-TRANSCRIPTION] ${msg}`);
+var log3 = (msg) => console.log(`[EXULU-TRANSCRIPTION] ${msg}`);
 var parseJsonField = (v) => {
   if (v == null) return null;
   if (typeof v === "string") {
@@ -14686,7 +14885,7 @@ var transcriptionService = {
         error: err.message,
         updatedAt: /* @__PURE__ */ new Date()
       }).returning("*");
-      log2(`Failed to dispatch job ${row.id}: ${err.message}`);
+      log3(`Failed to dispatch job ${row.id}: ${err.message}`);
       return this._rowFromDb(failed);
     }
   },
@@ -14714,9 +14913,9 @@ var transcriptionService = {
             updatedAt: /* @__PURE__ */ new Date()
           });
         } else if (err instanceof TranscriptionServerUnavailable) {
-          log2(`Whisper server unreachable while polling ${row.id}; will retry`);
+          log3(`Whisper server unreachable while polling ${row.id}; will retry`);
         } else {
-          log2(`Error polling job ${row.id}: ${err.message}`);
+          log3(`Error polling job ${row.id}: ${err.message}`);
         }
       }
     }
@@ -14766,7 +14965,7 @@ var transcriptionService = {
       } catch (err) {
         const code = err.code;
         if (code !== "JOB_NOT_FOUND") {
-          log2(`Best-effort cancel of whisper job failed: ${err.message}`);
+          log3(`Best-effort cancel of whisper job failed: ${err.message}`);
         }
       }
     }
@@ -14852,7 +15051,7 @@ var transcriptionService = {
           []
         );
       } catch (err) {
-        log2(`RBAC update failed for item ${itemId}: ${err.message}`);
+        log3(`RBAC update failed for item ${itemId}: ${err.message}`);
       }
     }
     const projectId = input.project_id ?? row.project_id ?? null;
@@ -15149,7 +15348,7 @@ var durationFromSegments = (segments) => {
 // src/exulu/recall/service.ts
 var TABLE3 = "transcription_jobs";
 var DEFAULT_BOT_NAME = "Exulu Notetaker";
-var log3 = (msg) => console.log(`[EXULU-RECALL] ${msg}`);
+var log4 = (msg) => console.log(`[EXULU-RECALL] ${msg}`);
 var parseJson = (v) => {
   if (v == null) return null;
   if (typeof v === "string") {
@@ -15246,7 +15445,7 @@ var recallService = {
         error: err.message,
         updatedAt: /* @__PURE__ */ new Date()
       }).returning("*");
-      log3(`createBot failed for job ${inserted.id}: ${err.message}`);
+      log4(`createBot failed for job ${inserted.id}: ${err.message}`);
       return this._row(failed);
     }
   },
@@ -15260,7 +15459,7 @@ var recallService = {
     const name = event?.event ?? "";
     const job = await this._findJob(ids.botId, ids.recordingId, ids.transcriptId);
     if (!job) {
-      log3(`No job for event ${name} (bot=${ids.botId}); ignoring.`);
+      log4(`No job for event ${name} (bot=${ids.botId}); ignoring.`);
       return;
     }
     if (name.startsWith("bot.")) {
@@ -15285,12 +15484,12 @@ var recallService = {
         await this._fail(job.id, ids.subCode || ids.code || "transcript failed");
         return;
       default:
-        log3(`Unhandled event ${name} for job ${job.id}`);
+        log4(`Unhandled event ${name} for job ${job.id}`);
     }
   },
   async _onRecordingDone(jobId, recordingId) {
     if (!recordingId) {
-      log3(`recording.done for job ${jobId} had no recording id`);
+      log4(`recording.done for job ${jobId} had no recording id`);
       return;
     }
     const { db: db2 } = await postgresClient();
@@ -15300,7 +15499,7 @@ var recallService = {
       updatedAt: /* @__PURE__ */ new Date()
     });
     if (!claimed) {
-      log3(`recording.done for job ${jobId} already handled; skipping.`);
+      log4(`recording.done for job ${jobId} already handled; skipping.`);
       return;
     }
     try {
@@ -15320,7 +15519,7 @@ var recallService = {
     if (!dbRow) return;
     const job = this._row(dbRow);
     if ((job.status === "awaiting_review" || job.status === "saved") && job.raw_segments && job.raw_segments.length > 0) {
-      log3(`transcript.done for job ${jobId} already processed; skipping.`);
+      log4(`transcript.done for job ${jobId} already processed; skipping.`);
       return;
     }
     try {
@@ -15339,7 +15538,7 @@ var recallService = {
           const recDuration = recordingDurationSeconds(rec);
           if (recDuration != null) duration = recDuration;
         } catch (err) {
-          log3(`could not fetch recording duration for job ${jobId}: ${err.message}`);
+          log4(`could not fetch recording duration for job ${jobId}: ${err.message}`);
         }
       }
       await this._update(jobId, {
@@ -15379,11 +15578,11 @@ var recallService = {
     const prompts = job.post_processing_prompts ?? [];
     if (prompts.length === 0) return [];
     if (job.post_processing_outputs && job.post_processing_outputs.length > 0) {
-      log3(`post-processing for job ${jobId} already ran; skipping.`);
+      log4(`post-processing for job ${jobId} already ran; skipping.`);
       return job.post_processing_outputs;
     }
     if (!job.raw_segments || job.raw_segments.length === 0) {
-      log3(`post-processing for job ${jobId} skipped: no transcript.`);
+      log4(`post-processing for job ${jobId} skipped: no transcript.`);
       return [];
     }
     const outputs = [];
@@ -15456,7 +15655,7 @@ ${transcriptText}`,
         ran_at: ranAt
       };
     } catch (err) {
-      log3(`post-processing prompt ${promptId} failed for job ${job.id}: ${err.message}`);
+      log4(`post-processing prompt ${promptId} failed for job ${job.id}: ${err.message}`);
       return {
         prompt_id: promptId,
         agent_id: agentId,
@@ -19655,6 +19854,53 @@ var verifyRecallRequest = (headers, rawBody, secret = recallVerificationSecret()
   return passed ? { ok: true } : { ok: false, reason: "signature mismatch" };
 };
 
+// src/exulu/shared-artifacts.ts
+init_cjs_shims();
+var import_bcryptjs4 = __toESM(require("bcryptjs"), 1);
+var normalizeS3Key = (key, bucket) => {
+  const segments = key.split("/").filter((s, i) => !(i === 0 && s === "")).map((s) => decodeURIComponent(s));
+  if (segments[0] === bucket) segments.shift();
+  return segments.join("/");
+};
+var isHtmlKey = (key) => /\.html?$/i.test(key);
+var deriveFilename = (key) => {
+  const base = key.split("/").pop() ?? key;
+  return base.split("_EXULU_").pop() ?? base;
+};
+var slugifyShareName = (input) => deriveFilename(input).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+var isExpired = (expiresAt, now) => {
+  if (!expiresAt) return false;
+  return new Date(expiresAt).getTime() <= now.getTime();
+};
+var validateCreateInput = (input, now) => {
+  if (!input.s3key) return { ok: false, message: "s3key is required." };
+  if (!input.name) return { ok: false, message: "name is required." };
+  const mode = input.auth_mode;
+  if (mode !== "public" && mode !== "password" && mode !== "regular") {
+    return { ok: false, message: "auth_mode must be public, password, or regular." };
+  }
+  if (mode === "password" && !input.password) {
+    return { ok: false, message: "A password is required for password mode." };
+  }
+  if (input.expires_at && Number.isNaN(new Date(input.expires_at).getTime())) {
+    return { ok: false, message: "expires_at is not a valid date." };
+  }
+  if (input.expires_at && isExpired(input.expires_at, now)) {
+    return { ok: false, message: "expires_at must be in the future." };
+  }
+  return { ok: true };
+};
+var hashSharePassword = (password) => import_bcryptjs4.default.hash(password, 10);
+var verifySharePassword = (password, hash) => import_bcryptjs4.default.compare(password, hash);
+var contentHeadersFor = (key, contentType, filename) => {
+  if (isHtmlKey(key)) return { contentType: "text/html; charset=utf-8" };
+  return {
+    contentType: contentType || "application/octet-stream",
+    disposition: `attachment; filename="${filename.replace(/"/g, "")}"`
+  };
+};
+var getSharedArtifactByName = (db2, name) => db2("shared_artifacts").where({ name }).first();
+
 // src/exulu/routes.ts
 var REQUEST_SIZE_LIMIT = "50mb";
 var getExuluVersionNumber = async () => {
@@ -19771,7 +20017,7 @@ var createExpressRoutes = async (app, providers, tools, contexts, config, evals,
     config,
     evals
   );
-  const server = new import_server4.ApolloServer({
+  const server = new import_server5.ApolloServer({
     cache: new import_utils5.InMemoryLRUCache(),
     schema,
     introspection: true
@@ -22689,6 +22935,126 @@ ${style.markdown}` : params.prompt;
     }
     res.status(204).send();
   });
+  app.post("/shared-artifacts", async (req, res) => {
+    const { db: db2 } = await postgresClient();
+    const auth = await requestValidators.authenticate(req);
+    if (!auth.user?.id) {
+      res.status(401).json({ detail: "Authentication required." });
+      return;
+    }
+    const now = /* @__PURE__ */ new Date();
+    const valid = validateCreateInput(req.body, now);
+    if (!valid.ok) {
+      res.status(400).json({ detail: valid.message });
+      return;
+    }
+    const bucket = config.fileUploads?.s3Bucket ?? "";
+    const s3key = normalizeS3Key(req.body.s3key, bucket);
+    const name = slugifyShareName(req.body.name);
+    if (!name) {
+      res.status(400).json({ detail: "name must contain url-safe characters." });
+      return;
+    }
+    const existing = await getSharedArtifactByName(db2, name);
+    if (existing) {
+      res.status(409).json({ detail: "That share name is already taken." });
+      return;
+    }
+    const auth_mode = req.body.auth_mode;
+    const password_hash = auth_mode === "password" ? await hashSharePassword(req.body.password) : null;
+    const rights_mode = auth_mode === "regular" ? req.body.rights_mode ?? "private" : "public";
+    const [row] = await db2("shared_artifacts").insert({
+      name,
+      s3key,
+      auth_mode,
+      password_hash,
+      expires_at: req.body.expires_at ?? null,
+      content_type: req.body.content_type ?? null,
+      rights_mode,
+      created_by: auth.user.id
+    }).returning("*");
+    if (auth_mode === "regular" && req.body.rbac) {
+      await handleRBACUpdate(db2, "shared_artifact", row.id, req.body.rbac, []);
+    }
+    res.status(201).json({ name: row.name });
+  });
+  app.get("/shared-artifacts/:name/meta", async (req, res) => {
+    const { db: db2 } = await postgresClient();
+    const row = await getSharedArtifactByName(db2, req.params.name ?? "");
+    if (!row) {
+      res.status(404).json({ detail: "Not found." });
+      return;
+    }
+    if (isExpired(row.expires_at, /* @__PURE__ */ new Date())) {
+      res.status(410).json({ detail: "This link has expired." });
+      return;
+    }
+    res.json({
+      auth_mode: row.auth_mode,
+      expires_at: row.expires_at,
+      filename: deriveFilename(row.s3key),
+      content_type: row.content_type,
+      is_html: /\.html?$/i.test(row.s3key)
+    });
+  });
+  app.get("/shared-artifacts/:name/content", async (req, res) => {
+    const { db: db2 } = await postgresClient();
+    const row = await getSharedArtifactByName(db2, req.params.name ?? "");
+    if (!row) {
+      res.status(404).json({ detail: "Not found." });
+      return;
+    }
+    if (isExpired(row.expires_at, /* @__PURE__ */ new Date())) {
+      res.status(410).json({ detail: "This link has expired." });
+      return;
+    }
+    if (row.auth_mode === "password") {
+      const pw = req.headers["x-share-password"] || "";
+      if (!row.password_hash || !await verifySharePassword(pw, row.password_hash)) {
+        res.status(401).json({ detail: "Incorrect password." });
+        return;
+      }
+    } else if (row.auth_mode === "regular") {
+      const viewer = await requestValidators.authenticate(req);
+      if (!viewer.user?.id) {
+        res.status(401).json({ detail: "Authentication required." });
+        return;
+      }
+      const rbac = await RBACResolver(
+        db2,
+        "shared_artifact",
+        row.id,
+        row.rights_mode || "private"
+      );
+      const ok = await checkRecordAccess({ ...row, RBAC: rbac }, "read", viewer.user);
+      if (!ok) {
+        res.status(403).json({ detail: "You don't have access to this artifact." });
+        return;
+      }
+    }
+    let bytes;
+    try {
+      bytes = await getS3ObjectBytes(row.s3key, config);
+    } catch (e) {
+      if (e?.name === "NoSuchKey" || e?.name === "NotFound" || e?.$metadata?.httpStatusCode === 404) {
+        res.status(404).json({ detail: "Artifact file not found." });
+        return;
+      }
+      console.error("[EXULU] shared-artifact content read failed", e);
+      res.status(500).json({ detail: "Failed to read artifact." });
+      return;
+    }
+    const headers = contentHeadersFor(
+      row.s3key,
+      row.content_type,
+      deriveFilename(row.s3key)
+    );
+    res.setHeader("Content-Type", headers.contentType);
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Cache-Control", "private, no-store");
+    if (headers.disposition) res.setHeader("Content-Disposition", headers.disposition);
+    res.send(bytes);
+  });
   app.use(import_express5.default.static("public"));
   await registerOpenAIGatewayRoutes(app, providers, tools, contexts, config);
   return app;
@@ -26668,6 +27034,83 @@ var RecursiveChunker = class _RecursiveChunker extends BaseChunker {
 // src/index.ts
 init_chunker();
 init_context();
+
+// src/exulu/read-api.ts
+init_cjs_shims();
+init_table_names();
+init_types();
+init_client();
+init_access_control();
+init_convert_context_to_table_definition();
+init_resolve_embedder();
+var authorizedRead = async (context, user, role, opts = {}) => {
+  if (!opts.itemIds?.length && !opts.externalIds?.length) {
+    throw new Error("authorizedRead requires itemIds or externalIds to constrain the read.");
+  }
+  const { db: db2 } = await postgresClient();
+  const table = convertContextToTableDefinition(context);
+  const itemsTable = getTableName(context.id);
+  const chunksTable = getChunksTableName(context.id);
+  const acUser = role && (!user.role || user.role.id !== role) ? { ...user, role: { ...user.role ?? {}, id: role } } : user;
+  let q = db2(chunksTable + " as chunks").select([
+    "chunks.id as chunk_id",
+    "chunks.source as chunk_source",
+    "chunks.content as chunk_content",
+    "chunks.chunk_index",
+    "chunks.metadata as chunk_metadata",
+    db2.raw('chunks."createdAt" as chunk_created_at'),
+    db2.raw('chunks."updatedAt" as chunk_updated_at'),
+    "items.id as item_id",
+    "items.name as item_name",
+    "items.external_id as item_external_id",
+    db2.raw('items."createdAt" as item_created_at'),
+    db2.raw('items."updatedAt" as item_updated_at')
+  ]);
+  q = q.leftJoin(itemsTable + " as items", "chunks.source", "items.id");
+  if (opts.itemIds?.length) q = q.whereIn("items.id", opts.itemIds);
+  if (opts.externalIds?.length) q = q.whereIn("items.external_id", opts.externalIds);
+  if (opts.chunkIndexRange) {
+    const { from, to } = opts.chunkIndexRange;
+    if (typeof from === "number") q = q.where("chunks.chunk_index", ">=", from);
+    if (typeof to === "number") q = q.where("chunks.chunk_index", "<=", to);
+  }
+  q = applyAccessControl(table, q, acUser, "items");
+  q = q.orderBy("chunks.source").orderBy("chunks.chunk_index");
+  return await q;
+};
+var entitiesAvailable = async (context) => {
+  if (!context.entities) return false;
+  const { db: db2 } = await postgresClient();
+  const table = getChunkEntitiesTableName(context.id);
+  const res = await db2.raw(
+    "SELECT to_regclass(?) IS NOT NULL AS exists",
+    [table]
+  );
+  return res.rows?.[0]?.exists === true;
+};
+var embedQuery = async (context, text, opts = {}) => {
+  const resolved = await resolveEmbedder({
+    model: context.embedder.model,
+    contextId: context.id,
+    contextName: context.name,
+    user: opts.user,
+    roleId: opts.role
+  });
+  const [vector] = await resolved.embed([text], { inputType: opts.inputType ?? "query" });
+  return vector ?? [];
+};
+var ExuluReadApi = {
+  getTableName,
+  getChunksTableName,
+  getEntitiesTableName,
+  getChunkEntitiesTableName,
+  entitiesAvailable,
+  authorizedRead,
+  embedQuery
+};
+
+// src/index.ts
+init_client();
 init_tool();
 init_sentence2();
 
@@ -26704,7 +27147,8 @@ var {
   promptFavoritesSchema: promptFavoritesSchema3,
   transcriptionJobsSchema: transcriptionJobsSchema3,
   imageGenerationsSchema: imageGenerationsSchema2,
-  oauthTokensSchema: oauthTokensSchema2
+  oauthTokensSchema: oauthTokensSchema2,
+  sharedArtifactsSchema: sharedArtifactsSchema2
 } = coreSchemas.get();
 var addMissingFields = async (knex, tableName, fields, skipFields = []) => {
   for (const field of fields) {
@@ -26748,6 +27192,7 @@ var up = async function(knex) {
     transcriptionJobsSchema3(),
     imageGenerationsSchema2(),
     oauthTokensSchema2(),
+    sharedArtifactsSchema2(),
     rbacSchema3(),
     agentsSchema3(),
     feedbackSchema3(),
@@ -27038,7 +27483,7 @@ var checkLiteLLMDatabaseSafety = (configPath) => {
 
 // src/exulu/litellm/db-init.ts
 var WARNING_BANNER = "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550";
-var warn = (lines) => {
+var warn2 = (lines) => {
   console.warn(`
 ${WARNING_BANNER}`);
   console.warn("\u26A0  [EXULU-LITELLM] CONFIGURATION WARNING");
@@ -27046,13 +27491,13 @@ ${WARNING_BANNER}`);
   console.warn(`${WARNING_BANNER}
 `);
 };
-var log4 = (line) => console.log(`[EXULU-LITELLM] ${line}`);
+var log5 = (line) => console.log(`[EXULU-LITELLM] ${line}`);
 var initLiteLLMDatabase = async (packageRoot) => {
   const configPath = process.env.LITELLM_CONFIG_PATH ?? (0, import_node_path9.resolve)(process.cwd(), "./config.litellm.yaml");
   const safety = checkLiteLLMDatabaseSafety(configPath);
   if (safety.ok && safety.reason === "no-litellm-db-mode") return;
   if (!safety.ok && safety.reason === "unparseable-url") {
-    warn([
+    warn2([
       `LiteLLM's database_url is not a valid postgres URL:`,
       `   ${safety.rawUrl}`,
       `Expected postgres://user:pass@host:port/database. Skipping setup.`
@@ -27061,7 +27506,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
   }
   if (!safety.ok && safety.reason === "shared-with-exulu") {
     const { exuluTarget } = safety;
-    warn([
+    warn2([
       `LiteLLM's database_url points to the SAME database Exulu uses:`,
       `   ${exuluTarget.host}:${exuluTarget.port}/${exuluTarget.database}`,
       ``,
@@ -27080,7 +27525,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     return;
   }
   const target = "litellmTarget" in safety ? safety.litellmTarget : void 0;
-  log4(
+  log5(
     `LiteLLM database mode detected (${target?.host}:${target?.port}/${target?.database}).`
   );
   const ensureDatabaseExists2 = async () => {
@@ -27092,7 +27537,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     } catch (err) {
       const code = err?.code;
       if (code !== "3D000") {
-        warn([
+        warn2([
           `Could not connect to LiteLLM's target database:`,
           `   ${err instanceof Error ? err.message : String(err)}`,
           ``,
@@ -27104,13 +27549,13 @@ var initLiteLLMDatabase = async (packageRoot) => {
       const url = new URL(litellmUrl);
       const targetDbName = url.pathname.replace(/^\//, "");
       if (!targetDbName) {
-        warn([`LiteLLM database_url has no database name; cannot auto-create.`]);
+        warn2([`LiteLLM database_url has no database name; cannot auto-create.`]);
         return false;
       }
       url.pathname = "/postgres";
-      log4(`Target database "${targetDbName}" does not exist; creating it\u2026`);
+      log5(`Target database "${targetDbName}" does not exist; creating it\u2026`);
       if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(targetDbName)) {
-        warn([
+        warn2([
           `Refusing to auto-create database "${targetDbName}" \u2014 name`,
           `contains characters that would require quoting. Create it`,
           `manually: createdb -h ${url.hostname} -U ${url.username} ${targetDbName}`
@@ -27121,10 +27566,10 @@ var initLiteLLMDatabase = async (packageRoot) => {
       try {
         await admin.connect();
         await admin.query(`CREATE DATABASE "${targetDbName}"`);
-        log4(`\u2713 Created database "${targetDbName}".`);
+        log5(`\u2713 Created database "${targetDbName}".`);
         return true;
       } catch (createErr) {
-        warn([
+        warn2([
           `Failed to auto-create database "${targetDbName}":`,
           `   ${createErr instanceof Error ? createErr.message : String(createErr)}`,
           ``,
@@ -27143,7 +27588,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     }
   };
   if (!await ensureDatabaseExists2()) return;
-  log4("Checking that the target database is safe to push into\u2026");
+  log5("Checking that the target database is safe to push into\u2026");
   const client2 = new import_pg.Client({ connectionString: litellmUrl });
   let foreignTables = [];
   try {
@@ -27159,7 +27604,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     );
     foreignTables = res.rows.map((r) => r.table_name);
   } catch (err) {
-    warn([
+    warn2([
       `Could not query LiteLLM's target database to verify it is safe`,
       `to push into:`,
       `   ${err instanceof Error ? err.message : String(err)}`,
@@ -27175,7 +27620,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     }
   }
   if (foreignTables.length > 0) {
-    warn([
+    warn2([
       `LiteLLM's target database contains ${foreignTables.length} table(s) that are NOT`,
       `part of LiteLLM's schema:`,
       ...foreignTables.slice(0, 10).map((t) => `   - ${t}`),
@@ -27191,7 +27636,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
   const venvLibDir = (0, import_node_path9.resolve)(packageRoot, "ee/python/.venv/lib");
   const pythonVersionDir = (0, import_node_fs9.existsSync)(venvLibDir) ? (0, import_node_fs9.readdirSync)(venvLibDir).find((entry) => /^python3\.\d+$/.test(entry)) : void 0;
   if (!pythonVersionDir) {
-    warn([
+    warn2([
       `Could not find a python3.* directory under ${venvLibDir}.`,
       `Run \`npm run python:setup\` to create the venv.`,
       `Skipping LiteLLM database setup.`
@@ -27205,7 +27650,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
   );
   const schemaPath = (0, import_node_path9.resolve)(litellmProxyDir, "schema.prisma");
   if (!(0, import_node_fs9.existsSync)(prismaCli)) {
-    warn([
+    warn2([
       `Prisma CLI not found at ${prismaCli}.`,
       `Run \`npm run python:setup\` to create the venv and install prisma.`,
       `Skipping LiteLLM database setup.`
@@ -27213,13 +27658,13 @@ var initLiteLLMDatabase = async (packageRoot) => {
     return;
   }
   if (!(0, import_node_fs9.existsSync)(schemaPath)) {
-    warn([
+    warn2([
       `LiteLLM Prisma schema not found at ${schemaPath}.`,
       `Re-run \`npm run python:setup\`. Skipping LiteLLM database setup.`
     ]);
     return;
   }
-  log4("Running `prisma db push` against LiteLLM's schema\u2026");
+  log5("Running `prisma db push` against LiteLLM's schema\u2026");
   const result = (0, import_node_child_process5.spawnSync)(prismaCli, ["db", "push", "--skip-generate"], {
     cwd: litellmProxyDir,
     env: {
@@ -27233,14 +27678,14 @@ var initLiteLLMDatabase = async (packageRoot) => {
     encoding: "utf8"
   });
   if (result.error) {
-    warn([
+    warn2([
       `Failed to launch prisma: ${result.error.message}`,
       `Skipping LiteLLM database setup.`
     ]);
     return;
   }
   if (result.status !== 0) {
-    warn([
+    warn2([
       `prisma db push exited with status ${result.status}.`,
       `stdout:`,
       ...(result.stdout || "(empty)").split("\n").map((l) => `   ${l}`),
@@ -27249,7 +27694,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     ]);
     return;
   }
-  log4("\u2713 LiteLLM database ready.");
+  log5("\u2713 LiteLLM database ready.");
 };
 
 // src/postgres/init-litellm-db.ts
@@ -28532,14 +28977,37 @@ ${setupResult.output || ""}`);
         model: config.processor.model ?? "mistral-ocr",
         ...config.attribution
       });
-      await new Promise((resolve8) => setTimeout(resolve8, Math.floor(Math.random() * 4e3) + 1e3));
-      const base64Pdf = buffer.toString("base64");
-      const ocrResponse = await withRetry(async () => {
-        return await resolved.ocr({
-          type: "document_url",
-          document_url: "data:application/pdf;base64," + base64Pdf
-        }, { includeImageBase64: false });
-      }, 10);
+      const maxPagesPerChunk = config.processor.maxPagesPerChunk ?? 25;
+      const chunksDir = path2.join(path2.dirname(paths.json), "ocr_chunks");
+      const splitResult = await executePythonScript({
+        scriptPath: "ee/python/documents/processing/split_pdf.py",
+        args: [paths.source, chunksDir, "--chunk-size", String(maxPagesPerChunk)],
+        timeout: 5 * 60 * 1e3
+      });
+      const pdfChunks = JSON.parse(splitResult.stdout);
+      console.log(`[EXULU] PDF split into ${pdfChunks.length} chunk(s) for OCR (max ${maxPagesPerChunk} pages each)`);
+      const chunkLimit = (0, import_p_limit.default)(3);
+      const chunkResults = await Promise.all(
+        pdfChunks.map(
+          (chunk, i) => chunkLimit(async () => {
+            await new Promise((resolve8) => setImmediate(resolve8));
+            await new Promise((resolve8) => setTimeout(resolve8, Math.floor(Math.random() * 1e3) + 200));
+            console.log(`[EXULU] OCR chunk ${i + 1}/${pdfChunks.length}: pages ${chunk.start_page}\u2013${chunk.end_page - 1}`);
+            const chunkBuffer = await fs5.promises.readFile(chunk.path);
+            const chunkBase64 = chunkBuffer.toString("base64");
+            const chunkResponse = await withRetry(async () => {
+              return await resolved.ocr({
+                type: "document_url",
+                document_url: "data:application/pdf;base64," + chunkBase64
+              }, { includeImageBase64: false });
+            }, 10);
+            return { pages: chunkResponse.pages, offset: chunk.start_page };
+          })
+        )
+      );
+      const mergedPages = chunkResults.sort((a, b) => a.offset - b.offset).flatMap(
+        ({ pages, offset }) => pages.map((p) => ({ ...p, index: p.index + offset }))
+      );
       const parser = new import_liteparse.LiteParse();
       const screenshots = await parser.screenshot(paths.source, void 0);
       await fs5.promises.mkdir(paths.images, { recursive: true });
@@ -28553,7 +29021,7 @@ ${setupResult.output || ""}`);
         );
         screenshot.imagePath = path2.join(paths.images, `${screenshot.pageNum}.png`);
       }
-      json = ocrResponse.pages.map((page) => ({
+      json = mergedPages.map((page) => ({
         page: page.index + 1,
         content: page.markdown,
         image: screenshots.find((s) => s.pageNum === page.index + 1)?.imagePath,
@@ -28887,9 +29355,11 @@ var ExuluPython = {
   ExuluProvider,
   ExuluPython,
   ExuluQueues,
+  ExuluReadApi,
   ExuluReranker,
   ExuluTool,
   ExuluTrajectoryRegistry,
   ExuluVariables,
-  defaultChunker
+  defaultChunker,
+  postgresClient
 });