@exulu/backend 1.67.0 → 1.69.0

package/dist/{chunk-ZPZKOT6I.js → chunk-IVC2M56U.js}

@@ -119,9 +119,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);
             });
@@ -362,9 +362,14 @@ var supervise = async (cfg) => {
   }
 };
 var _packageRoot;
+var _clientMode = false;
 var setLiteLLMPackageRoot = (root) => {
   _packageRoot = root;
 };
+var enableLiteLLMClientMode = () => {
+  if (internal.readyPromise) return;
+  _clientMode = true;
+};
 var startLiteLLMSupervisor = async (options = {}) => {
   if (!isLiteLLMEnabled()) return;
   if (internal.readyPromise) {
@@ -413,6 +418,27 @@ var startLiteLLMSupervisor = async (options = {}) => {
 };
 var waitForLiteLLMReady = async () => {
   if (!isLiteLLMEnabled()) return;
+  if (_clientMode) {
+    if (internal.state === "ready") return;
+    const host = process.env.LITELLM_HOST ?? "127.0.0.1";
+    const port = process.env.LITELLM_PORT ?? "4000";
+    const url = `http://${host}:${port}/health/liveliness`;
+    let res;
+    try {
+      res = await fetch(url, { method: "GET" });
+    } catch (err) {
+      throw new Error(
+        `LiteLLM proxy not reachable at ${url} (is the Exulu server process running?): ${err.message}`
+      );
+    }
+    if (!res.ok) {
+      throw new Error(
+        `LiteLLM proxy health probe at ${url} returned ${res.status}.`
+      );
+    }
+    internal.state = "ready";
+    return;
+  }
   if (!internal.readyPromise) {
     return startLiteLLMSupervisor();
   }
@@ -499,6 +525,12 @@ function buildTags(input) {
   if (input.routine_name) {
     candidates.push("routine_name_" + input.routine_name);
   }
+  if (input.context_id) {
+    candidates.push("context_id_" + input.context_id);
+  }
+  if (input.context_name) {
+    candidates.push("context_name_" + input.context_name);
+  }
   console.log("[EXULU] Candidates", candidates);
   const out = [];
   for (const candidate of candidates) {
@@ -851,11 +883,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);
@@ -866,7 +907,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)) {
@@ -1002,6 +1046,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) {
@@ -1090,7 +1135,12 @@ var getLiteLLMProvider = ({
     // 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
   });
 };
 async function resolveModel(input) {
@@ -1109,7 +1159,10 @@ async function resolveModel(input) {
     const litellm = getLiteLLMProvider({
       user,
       role: user?.role,
-      project,
+      // Fall back to the caller's own project (set on API keys) when no
+      // explicit request project is supplied, so API-triggered requests are
+      // attributed to the key's project.
+      project: project ?? user?.project,
       agent,
       team: user?.team,
       routine
@@ -1568,7 +1621,7 @@ var ExuluTool = class _ExuluTool {
       });
       providerapikey = resolved.apiKey;
     }
-    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-4B7BQ5G2.js");
+    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-ET6UI7YG.js");
     const tools = await convertExuluToolsToAiSdkTools2(
       [this],
       [],
@@ -1577,7 +1630,6 @@ var ExuluTool = class _ExuluTool {
       agent.tools,
       providerapikey,
       void 0,
-      void 0,
       user,
       config,
       void 0,
@@ -1843,6 +1895,111 @@ var createSessionItemsRetrievalTool = async ({
 import { z as z9 } from "zod";
 import { createBashTool } from "bash-tool";
 
+// src/exulu/resolve-reranker.ts
+import "fs";
+var ResolveRerankerError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ResolveRerankerError";
+  }
+};
+async function resolveReranker(input) {
+  const { model, contextId, contextName, user, userId, roleId, project, agent, routine } = input;
+  if (!isLiteLLMEnabled()) {
+    throw new ResolveRerankerError(
+      "LITELLM_NOT_CONFIGURED",
+      "resolveReranker requires EXULU_USE_LITELLM=true \u2014 reranking is served exclusively through the LiteLLM proxy."
+    );
+  }
+  try {
+    await waitForLiteLLMReady();
+  } catch (err) {
+    throw new ResolveRerankerError(
+      "LITELLM_NOT_READY",
+      `LiteLLM is not ready: ${err.message}`
+    );
+  }
+  const host = process.env.LITELLM_HOST ?? "127.0.0.1";
+  const port = process.env.LITELLM_PORT ?? "4000";
+  const masterKey = process.env.LITELLM_MASTER_KEY;
+  if (!masterKey) {
+    throw new ResolveRerankerError(
+      "LITELLM_NOT_CONFIGURED",
+      "LITELLM_MASTER_KEY is required when EXULU_USE_LITELLM=true"
+    );
+  }
+  const resolvedUserId = user?.id ?? userId;
+  if (resolvedUserId) await provisionDefaultUserBudget(resolvedUserId);
+  const role = user?.role;
+  const tags = buildTags({
+    user_id: resolvedUserId,
+    role_id: role?.id ?? roleId,
+    project_id: (project ?? user?.project)?.id,
+    agent_id: agent?.id,
+    team_id: user?.team?.id,
+    routine_id: routine?.id,
+    context_id: contextId,
+    user_name: !user ? void 0 : user.type === "api" ? user.firstname ?? user.email : user.email,
+    role_name: role?.name,
+    project_name: (project ?? user?.project)?.name,
+    agent_name: agent?.name,
+    team_name: user?.team?.name,
+    routine_name: routine?.name,
+    context_name: contextName
+  });
+  const endpoint = `http://${host}:${port}/v1/rerank`;
+  const rerank = async (query, chunks, opts) => {
+    try {
+      if (chunks.length === 0) return [];
+      const documents = chunks.map(
+        (c) => `${c.item_name ?? ""}: ${c.chunk_content ?? ""}`
+      );
+      const res = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${masterKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          model,
+          query,
+          documents,
+          // Default to scoring every document so callers can fully reorder; a
+          // caller can pass a smaller topN as an optimization hint.
+          top_n: opts?.topN ?? documents.length,
+          // LiteLLM reads metadata.tags for tag-based spend tracking.
+          metadata: { tags }
+        })
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(
+          `[EXULU] LiteLLM /v1/rerank returned ${res.status} for model "${model}": ${text}`
+        );
+      }
+      const json = await res.json();
+      if (!Array.isArray(json.results)) {
+        throw new Error(
+          `[EXULU] LiteLLM /v1/rerank returned no results for model "${model}".`
+        );
+      }
+      const reranked = json.results.filter(
+        (r) => typeof r.index === "number" && !!chunks[r.index]
+      ).map((r) => ({
+        ...chunks[r.index],
+        rerank_score: r.relevance_score ?? 0
+      }));
+      reranked.sort((a, b) => b.rerank_score - a.rerank_score);
+      return reranked;
+    } catch (err) {
+      console.error("[EXULU] Error reranking:", err);
+      return [];
+    }
+  };
+  return { model, rerank };
+}
+
 // ee/entitlements.ts
 var ENTITLEMENTS = {
   "rbac": false,
@@ -1895,7 +2052,7 @@ async function withRetry(generateFn, maxRetries = 3) {
       if (attempt === maxRetries) {
         throw error;
       }
-      await new Promise((resolve3) => setTimeout(resolve3, Math.pow(2, attempt) * 1e3));
+      await new Promise((resolve4) => setTimeout(resolve4, Math.pow(2, attempt) * 1e3));
     }
   }
   throw lastError;
@@ -2037,6 +2194,12 @@ var authentication = async ({
           user.team = team;
         }
       }
+      if (user?.project) {
+        const project = await db2.from("projects").select("*").where("id", user?.project).first();
+        if (project) {
+          user.project = project;
+        }
+      }
       if (!user) {
         return {
           error: true,
@@ -2102,6 +2265,18 @@ var authentication = async ({
             user.role = role;
           }
         }
+        if (user?.team) {
+          const team = await db2.from("teams").select("*").where("id", user?.team).first();
+          if (team) {
+            user.team = team;
+          }
+        }
+        if (user?.project) {
+          const project = await db2.from("projects").select("*").where("id", user?.project).first();
+          if (project) {
+            user.project = project;
+          }
+        }
         return {
           error: false,
           code: 200,
@@ -2270,7 +2445,7 @@ var uploadFile = async (file, fileName, config, options = {}, user, customBucket
       if (error.name === "SignatureDoesNotMatch" || error.name === "InvalidAccessKeyId" || error.name === "AccessDenied") {
         if (attempt < maxRetries) {
           const backoffMs = Math.pow(2, attempt) * 1e3;
-          await new Promise((resolve3) => setTimeout(resolve3, backoffMs));
+          await new Promise((resolve4) => setTimeout(resolve4, backoffMs));
           s3Client = void 0;
           getS3Client(config);
           continue;
@@ -2991,9 +3166,871 @@ var ExuluStorage = class {
   // todo add upload and delete methods
 };
 
+// src/exulu/table-names.ts
+var getTableName = (id) => sanitizeName(id) + "_items";
+var getChunksTableName = (id) => sanitizeName(id) + "_chunks";
+
 // src/exulu/context.ts
 import pgvector2 from "pgvector/knex";
 
+// ee/tokenizer.ts
+import { Tiktoken } from "tiktoken/lite";
+import { load } from "tiktoken/load";
+import registry2 from "tiktoken/registry.json" with { type: "json" };
+import models from "tiktoken/model_to_encoding.json" with { type: "json" };
+var ExuluTokenizer = class {
+  constructor() {
+  }
+  encoder = null;
+  async create(modelName) {
+    if (this.encoder) {
+      return this.encoder;
+    }
+    const time = performance.now();
+    console.log("[EXULU] Loading tokenizer.", modelName);
+    const model = await load(registry2[models[modelName]]);
+    console.log("[EXULU] Loaded tokenizer.", modelName, performance.now() - time);
+    const encoder = new Tiktoken(model.bpe_ranks, model.special_tokens, model.pat_str);
+    console.log("[EXULU] Set encoder.");
+    this.encoder = encoder;
+    return encoder;
+  }
+  async decode(tokens) {
+    if (!this.encoder) {
+      throw new Error("Tokenizer not initialized");
+    }
+    const text = this.encoder.decode(tokens);
+    return new TextDecoder().decode(text);
+  }
+  async decodeBatch(tokenSequences) {
+    if (!this.encoder) {
+      throw new Error("Tokenizer not initialized");
+    }
+    const promises = tokenSequences.map((tokens) => this.decode(tokens));
+    return await Promise.all(promises);
+  }
+  encode(text) {
+    if (!this.encoder) {
+      throw new Error("Tokenizer not initialized");
+    }
+    const time = performance.now();
+    console.log("[EXULU] Encoding text length: " + (text?.length || 0));
+    const tokens = this.encoder.encode(text);
+    console.log("[EXULU] Finished encoding text.", performance.now() - time);
+    return tokens;
+  }
+  async countTokensBatch(texts) {
+    if (!this.encoder) {
+      throw new Error("Tokenizer not initialized");
+    }
+    const promises = texts.map((text) => Promise.resolve(this.countTokens(text)));
+    return await Promise.all(promises);
+  }
+  countTokens(text) {
+    if (!this.encoder) {
+      throw new Error("Tokenizer not initialized");
+    }
+    const tokens = this.encoder.encode(text);
+    const count = tokens.length;
+    console.log("[EXULU] Token count.", count);
+    return count;
+  }
+  async free() {
+    console.log("[EXULU] Freeing tokenizer.");
+    if (this.encoder) {
+      this.encoder.free();
+    }
+  }
+};
+
+// src/chunking/types/base.ts
+var Chunk = class _Chunk {
+  /** The text of the chunk. */
+  text;
+  /** The starting index of the chunk in the original text. */
+  startIndex;
+  /** The ending index of the chunk in the original text. */
+  endIndex;
+  /** The number of tokens in the chunk. */
+  tokenCount;
+  /** Optional embedding for the chunk. */
+  embedding;
+  /**
+   * Constructs a new Chunk object.
+   *
+   * @param {ChunkData} data - The data to construct the Chunk from.
+   */
+  constructor(data) {
+    this.text = data.text;
+    this.startIndex = data.startIndex;
+    this.endIndex = data.endIndex;
+    this.tokenCount = data.tokenCount;
+    this.embedding = data.embedding;
+    if (this.startIndex > this.endIndex) {
+      throw new Error("Start index must be less than or equal to end index.");
+    }
+    if (this.tokenCount < 0) {
+      throw new Error("Token count must be a non-negative integer.");
+    }
+  }
+  /** Return a string representation of the Chunk.
+   *
+   * @returns {string} The text of the chunk.
+   */
+  toString() {
+    return this.text;
+  }
+  /** Return a detailed string representation of the Chunk.
+   *
+   * @returns {string} The detailed string representation of the Chunk.
+   */
+  toRepresentation() {
+    let repr = `Chunk(text='${this.text}', tokenCount=${this.tokenCount}, startIndex=${this.startIndex}, endIndex=${this.endIndex}`;
+    repr += ")";
+    return repr;
+  }
+  /** Return a slice of the chunk's text.
+   *
+   * @param {number} [start] - The starting index of the slice.
+   * @param {number} [end] - The ending index of the slice.
+   * @returns {string} The slice of the chunk's text.
+   */
+  slice(start, end) {
+    return this.text.slice(start, end);
+  }
+  /** Return the Chunk as a dictionary-like object.
+   *
+   * @returns {ChunkData} The dictionary-like object.
+   */
+  toDict() {
+    return {
+      text: this.text,
+      startIndex: this.startIndex,
+      endIndex: this.endIndex,
+      tokenCount: this.tokenCount,
+      embedding: this.embedding
+    };
+  }
+  /** Create a Chunk object from a dictionary-like object.
+   *
+   * @param {ChunkData} data - The dictionary-like object.
+   * @returns {Chunk} The Chunk object.
+   */
+  static fromDict(data) {
+    return new _Chunk({
+      text: data.text,
+      startIndex: data.startIndex,
+      endIndex: data.endIndex,
+      tokenCount: data.tokenCount,
+      embedding: data.embedding
+    });
+  }
+  /** Return a deep copy of the chunk.
+   *
+   * @returns {Chunk} The deep copy of the chunk.
+   */
+  copy() {
+    return _Chunk.fromDict(this.toDict());
+  }
+};
+
+// src/chunking/types/sentence.ts
+var Sentence = class _Sentence {
+  /** The text of the sentence */
+  text;
+  /** The starting index of the sentence in the original text */
+  startIndex;
+  /** The ending index of the sentence in the original text */
+  endIndex;
+  /** The number of tokens in the sentence */
+  tokenCount;
+  constructor(data) {
+    this.text = data.text;
+    this.startIndex = data.startIndex;
+    this.endIndex = data.endIndex;
+    this.tokenCount = data.tokenCount;
+  }
+  /** Return a string representation of the Sentence */
+  toString() {
+    return `Sentence(text=${this.text}, startIndex=${this.startIndex}, endIndex=${this.endIndex}, tokenCount=${this.tokenCount})`;
+  }
+  /** Return the Sentence as a dictionary-like object */
+  toDict() {
+    return {
+      text: this.text,
+      startIndex: this.startIndex,
+      endIndex: this.endIndex,
+      tokenCount: this.tokenCount
+    };
+  }
+  /** Create a Sentence object from a dictionary-like object */
+  static fromDict(data) {
+    return new _Sentence(data);
+  }
+};
+var SentenceChunk = class _SentenceChunk extends Chunk {
+  /** List of sentences in the chunk */
+  sentences;
+  constructor(data) {
+    super(data);
+    this.sentences = data.sentences;
+    this.embedding = data.embedding ?? void 0;
+  }
+  /**
+   * Returns a detailed string representation of the SentenceChunk, including its text, start and end indices, token count, and a list of all contained sentences with their metadata.
+   *
+   * This method overrides the base {@link Chunk} toString method to provide a more informative output, which is especially useful for debugging and logging. Each sentence in the chunk is represented using its own toString method, and all sentences are included in the output.
+   *
+   * @returns {string} A string describing the SentenceChunk and all its sentences, e.g.,
+   *   SentenceChunk(text=..., startIndex=..., endIndex=..., tokenCount=..., sentences=[Sentence(...), ...])
+   */
+  toString() {
+    const sentencesStr = this.sentences.map((s) => s.toString()).join(", ");
+    return `SentenceChunk(text=${this.text}, startIndex=${this.startIndex}, endIndex=${this.endIndex}, tokenCount=${this.tokenCount}, sentences=[${sentencesStr}])`;
+  }
+  /**
+   * Returns the SentenceChunk as a dictionary-like object.
+   *
+   * This method extends the base {@link Chunk} toDict method to include the sentences in the chunk.
+   *
+   * @returns {SentenceChunkData} A dictionary-like object containing the chunk's text, start and end indices, token count, and an array of sentence data.
+  /** Return the SentenceChunk as a dictionary-like object */
+  toDict() {
+    const baseDict = super.toDict();
+    return {
+      ...baseDict,
+      sentences: this.sentences.map((sentence) => sentence.toDict())
+    };
+  }
+  /**
+   * Creates a SentenceChunk object from a dictionary-like object.
+   *
+   * This method extends the base {@link Chunk} fromDict method to include the sentences in the chunk.
+   *
+   * @param {SentenceChunkData} data - A dictionary-like object containing the chunk's text, start and end indices, token count, and an array of sentence data.
+   * @returns {SentenceChunk} A new SentenceChunk object created from the provided dictionary-like object.
+   */
+  static fromDict(data) {
+    const sentences = data.sentences.map((sentence) => Sentence.fromDict(sentence));
+    return new _SentenceChunk({
+      text: data.text,
+      startIndex: data.startIndex,
+      endIndex: data.endIndex,
+      tokenCount: data.tokenCount,
+      sentences,
+      embedding: data.embedding ?? void 0
+    });
+  }
+};
+
+// src/chunking/base.ts
+var BaseChunker = class {
+  tokenizer;
+  _useConcurrency = true;
+  // Determines if batch processing uses Promise.all
+  constructor(tokenizer) {
+    this.tokenizer = tokenizer;
+  }
+  /**
+   * Returns a string representation of the chunker instance.
+   *
+   * @returns {string} The class name and constructor signature.
+   */
+  toString() {
+    return `${this.constructor.name}()`;
+  }
+  async call(textOrTexts, showProgress = false) {
+    if (typeof textOrTexts === "string") {
+      return this.chunk(textOrTexts);
+    } else if (Array.isArray(textOrTexts)) {
+      return this.chunkBatch(textOrTexts, showProgress);
+    } else {
+      throw new Error("Input must be a string or an array of strings.");
+    }
+  }
+  /**
+   * Process a batch of texts sequentially (one after another).
+   *
+   * @protected
+   * @param {string[]} texts - The texts to chunk.
+   * @param {boolean} [showProgress=false] - Whether to display progress in the console.
+   * @returns {Promise<Chunk[][]>} An array of chunked results for each input text.
+   */
+  async _sequential_batch_processing(texts, showProgress = false) {
+    const results = [];
+    const total = texts.length;
+    for (let i = 0; i < total; i++) {
+      if (showProgress && total > 1) {
+        const progress = Math.round((i + 1) / total * 100);
+        process.stdout.write(`Sequential processing: Document ${i + 1}/${total} (${progress}%)\r`);
+      }
+      results.push(await this.chunk(texts[i]));
+    }
+    if (showProgress && total > 1) {
+      process.stdout.write("\n");
+    }
+    return results;
+  }
+  /**
+   * Process a batch of texts concurrently using Promise.all.
+   *
+   * @protected
+   * @param {string[]} texts - The texts to chunk.
+   * @param {boolean} [showProgress=false] - Whether to display progress in the console.
+   * @returns {Promise<Chunk[][]>} An array of chunked results for each input text.
+   */
+  async _concurrent_batch_processing(texts, showProgress = false) {
+    const total = texts.length;
+    let completedCount = 0;
+    const updateProgress = () => {
+      if (showProgress && total > 1) {
+        completedCount++;
+        const progress = Math.round(completedCount / total * 100);
+        process.stdout.write(
+          `Concurrent processing: Document ${completedCount}/${total} (${progress}%)\r`
+        );
+      }
+    };
+    const chunkPromises = texts.map(
+      (text) => this.chunk(text).then((result) => {
+        updateProgress();
+        return result;
+      })
+    );
+    const results = await Promise.all(chunkPromises);
+    if (showProgress && total > 1 && completedCount > 0) {
+      process.stdout.write("\n");
+    }
+    return results;
+  }
+  /**
+   * Chunk a batch of texts, using either concurrent or sequential processing.
+   *
+   * If only one text is provided, processes it directly without batch overhead.
+   *
+   * @param {string[]} texts - The texts to chunk.
+   * @param {boolean} [showProgress=true] - Whether to display progress in the console.
+   * @returns {Promise<Chunk[][]>} An array of chunked results for each input text.
+   */
+  async chunkBatch(texts, showProgress = true) {
+    if (texts.length === 0) {
+      return [];
+    }
+    if (texts.length === 1) {
+      return [await this.chunk(texts[0])];
+    }
+    if (this._useConcurrency) {
+      return this._concurrent_batch_processing(texts, showProgress);
+    } else {
+      return this._sequential_batch_processing(texts, showProgress);
+    }
+  }
+};
+
+// src/chunking/sentence.ts
+var SentenceChunker = class _SentenceChunker extends BaseChunker {
+  chunkSize;
+  chunkOverlap;
+  minSentencesPerChunk;
+  minCharactersPerSentence;
+  approximate;
+  delim;
+  includeDelim;
+  sep;
+  /**
+   * Private constructor. Use `SentenceChunker.create()` to instantiate.
+   *
+   * @param {Tokenizer} tokenizer - The tokenizer to use for token counting.
+   * @param {number} chunkSize - Maximum number of tokens per chunk.
+   * @param {number} chunkOverlap - Number of tokens to overlap between consecutive chunks.
+   * @param {number} minSentencesPerChunk - Minimum number of sentences per chunk.
+   * @param {number} minCharactersPerSentence - Minimum number of characters for a valid sentence.
+   * @param {boolean} approximate - Whether to use approximate token counting.
+   * @param {string[]} delim - List of sentence delimiters to use for splitting.
+   * @param {('prev' | 'next' | null)} includeDelim - Whether to include the delimiter with the previous sentence ('prev'), next sentence ('next'), or exclude it (null).
+   */
+  constructor(tokenizer, chunkSize, chunkOverlap, minSentencesPerChunk, minCharactersPerSentence, approximate, delim, includeDelim) {
+    super(tokenizer);
+    if (chunkSize <= 0) {
+      throw new Error("chunkSize must be greater than 0");
+    }
+    if (chunkOverlap < 0) {
+      throw new Error("chunkOverlap must be non-negative");
+    }
+    if (chunkOverlap >= chunkSize) {
+      throw new Error("chunkOverlap must be less than chunkSize");
+    }
+    if (minSentencesPerChunk <= 0) {
+      throw new Error("minSentencesPerChunk must be greater than 0");
+    }
+    if (minCharactersPerSentence <= 0) {
+      throw new Error("minCharactersPerSentence must be greater than 0");
+    }
+    if (!delim) {
+      throw new Error("delim must be a list of strings or a string");
+    }
+    if (includeDelim !== "prev" && includeDelim !== "next" && includeDelim !== null) {
+      throw new Error("includeDelim must be 'prev', 'next' or null");
+    }
+    if (approximate) {
+      console.warn(
+        "Approximate has been deprecated and will be removed from next version onwards!"
+      );
+    }
+    this.chunkSize = chunkSize;
+    this.chunkOverlap = chunkOverlap;
+    this.minSentencesPerChunk = minSentencesPerChunk;
+    this.minCharactersPerSentence = minCharactersPerSentence;
+    this.approximate = approximate;
+    this.delim = delim;
+    this.includeDelim = includeDelim;
+    this.sep = "\u2704";
+  }
+  /**
+   * Creates and initializes a SentenceChunker instance that is directly callable.
+   *
+   * This method is a static factory function that returns a Promise resolving to a CallableSentenceChunker instance.
+   * The returned instance is a callable function that can be used to chunk text strings or arrays of text strings.
+   *
+   * @param {SentenceChunkerOptions} [options] - Options for configuring the SentenceChunker.
+   * @returns {Promise<CallableSentenceChunker>} A promise that resolves to a callable SentenceChunker instance.
+   *
+   * @example
+   * const chunker = await SentenceChunker.create();
+   * const chunks = await chunker("This is a sample text.");
+   * const batchChunks = await chunker(["Text 1", "Text 2"]);
+   *
+   * @see SentenceChunkerOptions
+   */
+  static async create(options = {}) {
+    const {
+      tokenizer = "gpt-3.5-turbo",
+      chunkSize = 512,
+      chunkOverlap = 0,
+      minSentencesPerChunk = 1,
+      minCharactersPerSentence = 12,
+      approximate = false,
+      delim = [". ", "! ", "? ", "\n"],
+      includeDelim = "prev"
+    } = options;
+    const tokenizerInstance = new ExuluTokenizer();
+    await tokenizerInstance.create(tokenizer);
+    const plainInstance = new _SentenceChunker(
+      tokenizerInstance,
+      chunkSize,
+      chunkOverlap,
+      minSentencesPerChunk,
+      minCharactersPerSentence,
+      approximate,
+      delim,
+      includeDelim
+    );
+    const callableFn = function(textOrTexts, showProgress) {
+      if (typeof textOrTexts === "string") {
+        return plainInstance.call(textOrTexts, showProgress);
+      } else {
+        return plainInstance.call(textOrTexts, showProgress);
+      }
+    };
+    Object.setPrototypeOf(callableFn, _SentenceChunker.prototype);
+    Object.assign(callableFn, plainInstance);
+    return callableFn;
+  }
+  // NOTE: The replace + split method is not the best/most efficient way in general to be doing this. It works well in python because python implements .replace and .split in C while the re library is much slower in python.
+  // NOTE: The new split -> join -> split is so weird, but it works. I don't quite like it however.
+  // TODO: Implement a more efficient method for splitting text into sentences.
+  /**
+   * Fast sentence splitting while maintaining accuracy.
+   *
+   * @param {string} text - The text to split into sentences.
+   * @returns {string[]} An array of sentences.
+   */
+  _splitText(text) {
+    let t = text;
+    for (const c of this.delim) {
+      if (this.includeDelim === "prev") {
+        t = t.split(c).join(c + this.sep);
+      } else if (this.includeDelim === "next") {
+        t = t.split(c).join(this.sep + c);
+      } else {
+        t = t.split(c).join(this.sep);
+      }
+    }
+    const splits = t.split(this.sep);
+    const sentences = [];
+    let current = "";
+    for (const s of splits) {
+      if (!current) {
+        current = s;
+      } else {
+        if (current.length >= this.minCharactersPerSentence) {
+          sentences.push(current);
+          current = s;
+        } else {
+          current += s;
+        }
+      }
+    }
+    if (current) {
+      sentences.push(current);
+    }
+    return sentences;
+  }
+  /**
+   * Split text into sentences and calculate token counts for each sentence.
+   *
+   * @param {string} text - The text to split into sentences.
+   * @returns {Promise<Sentence[]>} An array of Sentence objects.
+   */
+  async _prepareSentences(text) {
+    const sentenceTexts = this._splitText(text);
+    if (!sentenceTexts.length) {
+      return [];
+    }
+    const positions = [];
+    let currentPos = 0;
+    for (const sent of sentenceTexts) {
+      positions.push(currentPos);
+      currentPos += sent.length;
+    }
+    const tokenCounts = await this.tokenizer.countTokensBatch(sentenceTexts);
+    return sentenceTexts.map(
+      (sent, i) => new Sentence({
+        text: sent,
+        startIndex: positions[i],
+        endIndex: positions[i] + sent.length,
+        tokenCount: tokenCounts[i]
+      })
+    );
+  }
+  /**
+   * Create a chunk from a list of sentences.
+   *
+   * @param {Sentence[]} sentences - The sentences to create a chunk from.
+   * @returns {Promise<SentenceChunk>} A promise that resolves to a SentenceChunk object.
+   */
+  async _createChunk(sentences) {
+    const chunkText = sentences.map((sentence) => sentence.text).join("");
+    const tokenCount = this.tokenizer.countTokens(chunkText);
+    return new SentenceChunk({
+      text: chunkText,
+      startIndex: sentences[0].startIndex,
+      endIndex: sentences[sentences.length - 1].endIndex,
+      tokenCount,
+      sentences
+    });
+  }
+  /**
+   * Split text into overlapping chunks based on sentences while respecting token limits.
+   *
+   * @param {string} text - The text to split into chunks.
+   * @returns {Promise<SentenceChunk[]>} A promise that resolves to an array of SentenceChunk objects.
+   */
+  async chunk(text) {
+    if (!text.trim()) {
+      return [];
+    }
+    const sentences = await this._prepareSentences(text);
+    if (!sentences.length) {
+      return [];
+    }
+    const tokenSums = [];
+    let sum = 0;
+    for (const sentence of sentences) {
+      tokenSums.push(sum);
+      sum += sentence.tokenCount;
+    }
+    tokenSums.push(sum);
+    const chunks = [];
+    let pos = 0;
+    while (pos < sentences.length) {
+      const targetTokens = tokenSums[pos] + this.chunkSize;
+      let splitIdx = this._bisectLeft(tokenSums, targetTokens, pos) - 1;
+      splitIdx = Math.min(splitIdx, sentences.length);
+      splitIdx = Math.max(splitIdx, pos + 1);
+      if (splitIdx - pos < this.minSentencesPerChunk) {
+        if (pos + this.minSentencesPerChunk <= sentences.length) {
+          splitIdx = pos + this.minSentencesPerChunk;
+        } else {
+          console.warn(
+            `Minimum sentences per chunk as ${this.minSentencesPerChunk} could not be met for all chunks. Last chunk of the text will have only ${sentences.length - pos} sentences. Consider increasing the chunk_size or decreasing the min_sentences_per_chunk.`
+          );
+          splitIdx = sentences.length;
+        }
+      }
+      const chunkSentences = sentences.slice(pos, splitIdx);
+      chunks.push(await this._createChunk(chunkSentences));
+      if (this.chunkOverlap > 0 && splitIdx < sentences.length) {
+        let overlapTokens = 0;
+        let overlapIdx = splitIdx - 1;
+        while (overlapIdx > pos && overlapTokens < this.chunkOverlap) {
+          const sent = sentences[overlapIdx];
+          const nextTokens = overlapTokens + sent.tokenCount + 1;
+          if (nextTokens > this.chunkOverlap) {
+            break;
+          }
+          overlapTokens = nextTokens;
+          overlapIdx--;
+        }
+        pos = overlapIdx + 1;
+      } else {
+        pos = splitIdx;
+      }
+    }
+    await this.tokenizer.free();
+    return chunks;
+  }
+  /**
+   * Binary search to find the leftmost position where value should be inserted to maintain order.
+   *
+   * @param {number[]} arr - The array to search.
+   * @param {number} value - The value to search for.
+   * @param {number} [lo] - The starting index of the search.
+   * @returns {number} The index of the leftmost position where value should be inserted.
+   */
+  _bisectLeft(arr, value, lo = 0) {
+    let hi = arr.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (arr[mid] < value) {
+        lo = mid + 1;
+      } else {
+        hi = mid;
+      }
+    }
+    return lo;
+  }
+  /**
+   * Return a string representation of the SentenceChunker.
+   *
+   * @returns {string} A string representation of the SentenceChunker.
+   */
+  toString() {
+    return `SentenceChunker(tokenizer=${JSON.stringify(this.tokenizer)}, chunkSize=${this.chunkSize}, chunkOverlap=${this.chunkOverlap}, minSentencesPerChunk=${this.minSentencesPerChunk}, minCharactersPerSentence=${this.minCharactersPerSentence}, approximate=${this.approximate}, delim=${JSON.stringify(this.delim)}, includeDelim=${this.includeDelim})`;
+  }
+};
+
+// src/exulu/chunker.ts
+var defaultChunker = async (item, maxChunkSize) => {
+  const body = typeof item.content === "string" && item.content || typeof item.description === "string" && item.description || "";
+  const name = typeof item.name === "string" ? item.name : "";
+  const text = [name, body].filter(Boolean).join("\n\n").trim();
+  if (!text) {
+    return { item, chunks: [] };
+  }
+  const chunker = await SentenceChunker.create({ chunkSize: maxChunkSize });
+  const sentenceChunks = await chunker(text);
+  const chunks = sentenceChunks.map((c, index) => ({ content: c.text.trim(), index })).filter((c) => c.content.length > 0).map((c, index) => ({ content: c.content, index }));
+  return { item, chunks };
+};
+
+// src/exulu/litellm/parse-embedding-models.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+var DEFAULT_MAX_CHUNK_SIZE = 1024;
+var DEFAULT_MAX_BATCH_SIZE = 100;
+var stripComment = (line) => {
+  const idx = line.indexOf("#");
+  return idx >= 0 ? line.slice(0, idx) : line;
+};
+var parseInt10 = (raw) => {
+  const n = Number(raw.trim());
+  return Number.isInteger(n) ? n : void 0;
+};
+var resolveLiteLLMConfigPath = () => process.env.LITELLM_CONFIG_PATH ?? resolve2(process.cwd(), "./config.litellm.yaml");
+var parseEmbeddingModels = (configPath) => {
+  if (!existsSync2(configPath)) return [];
+  const text = readFileSync(configPath, "utf8");
+  const lines = text.split("\n");
+  const entries = [];
+  let current;
+  for (const rawLine of lines) {
+    const noComment = stripComment(rawLine);
+    if (!noComment.trim()) continue;
+    const indent = (rawLine.match(/^\s*/)?.[0] ?? "").length;
+    const modelNameMatch = noComment.match(
+      /^\s*-\s*model_name\s*:\s*["']?([^"'\s#]+)["']?\s*$/
+    );
+    if (modelNameMatch) {
+      if (current) entries.push(current);
+      current = { model_name: modelNameMatch[1], indent };
+      continue;
+    }
+    if (!current) continue;
+    if (indent <= current.indent && !/^\s*-\s/.test(rawLine)) {
+      entries.push(current);
+      current = void 0;
+      continue;
+    }
+    const kvMatch = noComment.match(/^\s*(\w+)\s*:\s*(.+?)\s*$/);
+    if (!kvMatch) continue;
+    const key = kvMatch[1] ?? "";
+    const rawValue = kvMatch[2] ?? "";
+    switch (key) {
+      case "dimensionality": {
+        current.dimensionality = parseInt10(rawValue);
+        break;
+      }
+      case "max_chunk_size": {
+        current.max_chunk_size = parseInt10(rawValue);
+        break;
+      }
+      case "max_batch_size": {
+        current.max_batch_size = parseInt10(rawValue);
+        break;
+      }
+    }
+  }
+  if (current) entries.push(current);
+  return entries.filter((e) => typeof e.dimensionality === "number" && e.dimensionality > 0).map((e) => ({
+    model_name: e.model_name,
+    dimensionality: e.dimensionality,
+    maxChunkSize: typeof e.max_chunk_size === "number" && e.max_chunk_size > 0 ? e.max_chunk_size : DEFAULT_MAX_CHUNK_SIZE,
+    maxBatchSize: typeof e.max_batch_size === "number" && e.max_batch_size > 0 ? e.max_batch_size : DEFAULT_MAX_BATCH_SIZE
+  }));
+};
+var getEmbeddingModelInfo = (modelName, configPath = resolveLiteLLMConfigPath()) => {
+  const models2 = parseEmbeddingModels(configPath);
+  const found = models2.find((m) => m.model_name === modelName);
+  if (!found) {
+    throw new Error(
+      `[EXULU] Embedding model "${modelName}" was not found in ${configPath}, or its entry is missing a numeric \`model_info.dimensionality\`. Add it, e.g.:
+  - model_name: ${modelName}
+    litellm_params:
+      model: <provider>/${modelName}
+    model_info:
+      dimensionality: 1024   # required (matches the model's output size)
+      max_chunk_size: 1024   # optional
+      max_batch_size: 100    # optional`
+    );
+  }
+  return found;
+};
+
+// src/exulu/resolve-embedder.ts
+var ResolveEmbedderError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ResolveEmbedderError";
+  }
+};
+async function resolveEmbedder(input) {
+  const { model, contextId, contextName, user, userId, roleId, project, agent, routine } = input;
+  if (!isLiteLLMEnabled()) {
+    throw new ResolveEmbedderError(
+      "LITELLM_NOT_CONFIGURED",
+      "resolveEmbedder requires EXULU_USE_LITELLM=true \u2014 embeddings are served exclusively through the LiteLLM proxy."
+    );
+  }
+  try {
+    await waitForLiteLLMReady();
+  } catch (err) {
+    throw new ResolveEmbedderError(
+      "LITELLM_NOT_READY",
+      `LiteLLM is not ready: ${err.message}`
+    );
+  }
+  const host = process.env.LITELLM_HOST ?? "127.0.0.1";
+  const port = process.env.LITELLM_PORT ?? "4000";
+  const masterKey = process.env.LITELLM_MASTER_KEY;
+  if (!masterKey) {
+    throw new ResolveEmbedderError(
+      "LITELLM_NOT_CONFIGURED",
+      "LITELLM_MASTER_KEY is required when EXULU_USE_LITELLM=true"
+    );
+  }
+  const resolvedUserId = user?.id ?? userId;
+  if (resolvedUserId) await provisionDefaultUserBudget(resolvedUserId);
+  const { dimensionality, maxChunkSize, maxBatchSize } = getEmbeddingModelInfo(model);
+  const role = user?.role;
+  const tags = buildTags({
+    user_id: resolvedUserId,
+    role_id: role?.id ?? roleId,
+    project_id: (project ?? user?.project)?.id,
+    agent_id: agent?.id,
+    team_id: user?.team?.id,
+    routine_id: routine?.id,
+    context_id: contextId,
+    user_name: !user ? void 0 : user.type === "api" ? user.firstname ?? user.email : user.email,
+    role_name: role?.name,
+    project_name: (project ?? user?.project)?.name,
+    agent_name: agent?.name,
+    team_name: user?.team?.name,
+    routine_name: routine?.name,
+    context_name: contextName
+  });
+  const endpoint = `http://${host}:${port}/v1/embeddings`;
+  const embedBatch = async (batch) => {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${masterKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        model,
+        input: batch,
+        encoding_format: "float",
+        // Pin the output size to the configured column dimensions. LiteLLM's
+        // `drop_params: true` silently drops this for providers that don't
+        // support it; for those, a dimensionality mismatch surfaces as an
+        // insert error (the correct fail-fast).
+        dimensions: dimensionality,
+        // LiteLLM reads metadata.tags for tag-based spend tracking — same
+        // mechanism createTaggedFetch uses for chat completions.
+        metadata: { tags }
+      })
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `[EXULU] LiteLLM /v1/embeddings returned ${res.status} for model "${model}": ${text}`
+      );
+    }
+    const json = await res.json();
+    const data = json.data ?? [];
+    const ordered = [...data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    const vectors = ordered.map((d) => d.embedding ?? []);
+    if (vectors.length !== batch.length) {
+      throw new Error(
+        `[EXULU] LiteLLM /v1/embeddings returned ${vectors.length} vectors for ${batch.length} inputs (model "${model}").`
+      );
+    }
+    return vectors;
+  };
+  const embed = async (inputs) => {
+    if (inputs.length === 0) return [];
+    const out = [];
+    for (let i = 0; i < inputs.length; i += maxBatchSize) {
+      const batch = inputs.slice(i, i + maxBatchSize);
+      const vectors = await embedBatch(batch);
+      out.push(...vectors);
+    }
+    return out;
+  };
+  return {
+    model,
+    dimensions: dimensionality,
+    maxChunkSize,
+    maxBatchSize,
+    embed
+  };
+}
+
+// types/enums/statistics.ts
+var STATISTICS_TYPE_ENUM = {
+  CONTEXT_RETRIEVE: "CONTEXT_RETRIEVE",
+  SOURCE_UPDATE: "SOURCE_UPDATE",
+  EMBEDDER_UPSERT: "EMBEDDER_UPSERT",
+  EMBEDDER_GENERATE: "EMBEDDER_GENERATE",
+  EMBEDDER_DELETE: "EMBEDDER_DELETE",
+  WORKFLOW_RUN: "WORKFLOW_RUN",
+  CONTEXT_UPSERT: "CONTEXT_UPSERT",
+  TOOL_CALL: "TOOL_CALL",
+  AGENT_RUN: "AGENT_RUN"
+};
+
 // src/utils/query-preprocessing.ts
 import { franc } from "franc";
 import natural from "natural";
@@ -3266,19 +4303,6 @@ var applyFilters = (query, filters, table, field_prefix) => {
   return query;
 };
 
-// types/enums/statistics.ts
-var STATISTICS_TYPE_ENUM = {
-  CONTEXT_RETRIEVE: "CONTEXT_RETRIEVE",
-  SOURCE_UPDATE: "SOURCE_UPDATE",
-  EMBEDDER_UPSERT: "EMBEDDER_UPSERT",
-  EMBEDDER_GENERATE: "EMBEDDER_GENERATE",
-  EMBEDDER_DELETE: "EMBEDDER_DELETE",
-  WORKFLOW_RUN: "WORKFLOW_RUN",
-  CONTEXT_UPSERT: "CONTEXT_UPSERT",
-  TOOL_CALL: "TOOL_CALL",
-  AGENT_RUN: "AGENT_RUN"
-};
-
 // types/models/vector-methods.ts
 var VectorMethodEnum = {
   "cosineDistance": "cosineDistance",
@@ -3939,6 +4963,11 @@ var agentsSchema = {
     {
       name: "animation_responding",
       type: "text"
+    },
+    {
+      name: "sandbox_enabled",
+      type: "boolean",
+      default: false
     }
   ]
 };
@@ -4027,6 +5056,15 @@ var usersSchema = {
       name: "favourite_items",
       type: "json"
     },
+    {
+      // Knowledge: per-user "recently viewed" data items. Ordered JSON array
+      // of global item ids ("<contextId>/<itemId>"), most-recent first, capped
+      // client-side. Auto-added to existing DBs by the init-exulu-db column
+      // sync; read via userById, written via usersUpdateOne (mirrors
+      // favourite_items).
+      name: "recently_viewed_items",
+      type: "json"
+    },
     {
       name: "firstname",
       type: "text"
@@ -4106,6 +5144,12 @@ var usersSchema = {
     {
       name: "team",
       type: "uuid"
+    },
+    {
+      // Optional attribution target for API keys (type "api"): tags requests
+      // triggered by the key with project_id_ for LiteLLM cost attribution.
+      name: "project",
+      type: "uuid"
     }
   ]
 };
@@ -4135,35 +5179,6 @@ var platformConfigurationsSchema = {
     }
   ]
 };
-var embedderSettingsSchema = {
-  type: "embedder_settings",
-  name: {
-    plural: "embedder_settings",
-    singular: "embedder_setting"
-  },
-  RBAC: false,
-  fields: [
-    {
-      name: "context",
-      type: "text"
-      // id of the ExuluContext class
-    },
-    {
-      name: "embedder",
-      type: "text"
-      // id of the ExuluEmbedder class
-    },
-    {
-      name: "name",
-      type: "text"
-    },
-    {
-      name: "value",
-      type: "text"
-      // reference to an exulu variable
-    }
-  ]
-};
 var entityTypeSettingsSchema = {
   type: "entity_type_settings",
   name: {
@@ -4191,6 +5206,13 @@ var entityTypeSettingsSchema = {
       name: "active",
       type: "boolean",
       default: true
+    },
+    {
+      // "active" = a configured type (used in extraction); "suggested" = a type
+      // the extractor proposed (active:false) awaiting promotion on the UI.
+      name: "status",
+      type: "text",
+      default: "active"
     }
   ]
 };
@@ -4282,7 +5304,21 @@ var transcriptionJobsSchema = {
     { name: "target_rbac_users", type: "json" },
     { name: "target_rbac_roles", type: "json" },
     { name: "saved_item_id", type: "uuid", required: false },
-    { name: "error", type: "text" }
+    { name: "error", type: "text" },
+    // Recall.ai meeting-bot fields. source discriminates the pipeline: whisper
+    // rows are driven by the polling loop, recall rows by webhooks.
+    // Design doc: docs/superpowers/specs/2026-06-19-recall-meeting-recording-design.md
+    { name: "source", type: "text", default: "whisper", index: true },
+    { name: "meeting_url", type: "text" },
+    { name: "recall_bot_id", type: "text", index: true },
+    { name: "recall_recording_id", type: "text", index: true },
+    { name: "recall_transcript_id", type: "text", index: true },
+    { name: "bot_status", type: "text" },
+    { name: "join_at", type: "date" },
+    // Selected per-meeting post-processing: [{ prompt_id, agent_id }].
+    { name: "post_processing_prompts", type: "json" },
+    // Results: [{ prompt_id, agent_id, prompt_name, status, output, error, ran_at }].
+    { name: "post_processing_outputs", type: "json" }
   ]
 };
 var imageGenerationsSchema = {
@@ -4337,6 +5373,26 @@ var oauthTokensSchema = {
     // null = non-expiring
   ]
 };
+var 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 }
+  ]
+};
 var contextPresetsSchema = {
   type: "context_presets",
   name: {
@@ -4425,11 +5481,11 @@ var coreSchemas = {
       variablesSchema: () => addCoreFields(variablesSchema),
       platformConfigurationsSchema: () => addCoreFields(platformConfigurationsSchema),
       promptLibrarySchema: () => addCoreFields(promptLibrarySchema),
-      embedderSettingsSchema: () => addCoreFields(embedderSettingsSchema),
       entityTypeSettingsSchema: () => addCoreFields(entityTypeSettingsSchema),
       promptFavoritesSchema: () => addCoreFields(promptFavoritesSchema),
       contextPresetsSchema: () => addCoreFields(contextPresetsSchema),
       oauthTokensSchema: () => addCoreFields(oauthTokensSchema),
+      sharedArtifactsSchema: () => addCoreFields(sharedArtifactsSchema),
       transcriptionJobsSchema: () => addCoreFields(transcriptionJobsSchema),
       imageGenerationsSchema: () => addCoreFields(imageGenerationsSchema)
     };
@@ -4560,11 +5616,89 @@ var entitiesEnabled = async (context) => {
   const types = await hydrateEntityTypes(context);
   return types.length > 0;
 };
+var upsertEntitySuggestions = async (context, suggestions) => {
+  if (!suggestions.length) return;
+  try {
+    const { db: db2 } = await postgresClient();
+    const existing = await db2.from("entity_type_settings").where({ context: context.id }).select("name");
+    const existingNames = new Set(
+      existing.map(
+        (r) => String(r.name || "").toLowerCase().trim()
+      )
+    );
+    const rows = suggestions.filter((s) => s.name && !existingNames.has(s.name.toLowerCase().trim())).map((s) => ({
+      name: s.name,
+      description: s.example ? `${s.description} (e.g. ${s.example})` : s.description,
+      context: context.id,
+      active: false,
+      status: "suggested"
+    }));
+    if (rows.length) {
+      await db2.from("entity_type_settings").insert(rows);
+    }
+  } catch (err) {
+    console.warn(
+      "[EXULU] Could not persist entity suggestions:",
+      err.message
+    );
+  }
+};
+var entityModelKey = (contextId) => `entity_extraction_model:${contextId}`;
+var getEntityModelSetting = async (contextId) => {
+  try {
+    const { db: db2 } = await postgresClient();
+    const row = await db2.from("platform_configurations").where({ config_key: entityModelKey(contextId) }).first();
+    if (!row?.config_value) return null;
+    const raw = row.config_value;
+    let value = raw;
+    if (typeof raw === "string") {
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        value = raw;
+      }
+    }
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+  } catch (err) {
+    console.warn("[EXULU] Could not read entity model setting:", err.message);
+    return null;
+  }
+};
+var setEntityModelSetting = async (contextId, modelId) => {
+  const { db: db2 } = await postgresClient();
+  const key = entityModelKey(contextId);
+  if (!modelId || !modelId.trim()) {
+    await db2.from("platform_configurations").where({ config_key: key }).del();
+    return;
+  }
+  const value = JSON.stringify(modelId.trim());
+  await db2.from("platform_configurations").insert({
+    config_key: key,
+    config_value: value,
+    description: `Entity extraction model for context ${contextId}`
+  }).onConflict("config_key").merge({ config_value: value });
+};
+var resolveEntityModel = async (context) => {
+  const databaseModel = await getEntityModelSetting(context.id);
+  const codeModel = context.entities?.model ?? null;
+  const envModel = process.env.EXULU_ENTITY_EXTRACTION_MODEL ?? null;
+  if (databaseModel) {
+    return { effectiveModel: databaseModel, source: "database", databaseModel, codeModel };
+  }
+  if (codeModel) {
+    return { effectiveModel: codeModel, source: "code", databaseModel, codeModel };
+  }
+  if (envModel) {
+    return { effectiveModel: envModel, source: "env", databaseModel, codeModel };
+  }
+  return { effectiveModel: null, source: null, databaseModel, codeModel };
+};
 
 // src/exulu/entities/extractor.ts
 import { generateText as generateText2, Output as Output2 } from "ai";
 import { z as z5 } from "zod";
 var CHUNK_BATCH_SIZE = 30;
+var MAX_SUGGESTIONS = 5;
 var mentionSchema = z5.object({
   entities: z5.array(
     z5.object({
@@ -4574,23 +5708,51 @@ var mentionSchema = z5.object({
       canonical: z5.string().describe("The canonical, language-normalized name used to merge variants."),
       confidence: z5.number().min(0).max(1).describe("Confidence 0..1 that this is a valid entity.")
     })
-  )
+  ),
+  suggestedTypes: z5.array(
+    z5.object({
+      name: z5.string().describe("A concise NEW entity type name, e.g. 'Error Code', 'Component'."),
+      description: z5.string().describe("What this type captures, one sentence."),
+      mentions: z5.array(
+        z5.object({
+          chunkIndex: z5.number().int().describe("Index of the chunk this mention was found in."),
+          mention: z5.string().describe("The exact surface form as it appears in the text."),
+          canonical: z5.string().describe("Canonical, language-normalized name."),
+          confidence: z5.number().min(0).max(1).describe("Confidence 0..1.")
+        })
+      ).describe("Every mention of this new type found in the provided chunks.")
+    })
+  ).describe(
+    "Entity TYPES that recur in the text but are NOT in the configured list and would be worth tracking. Empty array if none."
+  ).optional()
 });
 var buildSystemPrompt = (types, canonicalLanguage) => {
   const typeList = types.map((t) => `- ${t.name}: ${t.description}`).join("\n");
+  const typeNames = types.map((t) => `"${t.name}"`).join(", ");
   return [
-    "You are an entity extraction engine. Extract entities of ONLY the following types from the provided text chunks.",
+    "You are an entity extraction engine. Extract entities of ONLY the types listed below from the provided text chunks.",
     "",
-    "Entity types:",
+    'Entity types (the "type" field of every entity you output MUST be exactly one of these names):',
     typeList,
     "",
+    "For each entity, output an object with:",
+    `- "type": EXACTLY one of these type names \u2014 ${typeNames}. NEVER put the description, a category value, or a generic label like "named entity"/"classification" in this field.`,
+    '- "mention" and "canonical": the value (see how to choose them below).',
+    '- "chunkIndex": the index of the chunk the entity was found in.',
+    '- "confidence": your certainty the entity is valid (0..1).',
+    "",
+    "How to choose mention/canonical depends on each type's description:",
+    `- If the type names concrete things mentioned in the text (a person, product, place, code, organization): output the exact surface form as it appears as "mention", and a "canonical" normalized to ${canonicalLanguage}. Output a SEPARATE entity object for every distinct value \u2014 a single chunk may contain many of these, including several of the SAME type (e.g. three different cities \u2192 three "City" entities) and several of different types. Never collapse them or limit yourself to one per chunk.`,
+    `- If the type is a classification or property (the description defines a fixed set of categories, or asks you to judge a property of the content \u2014 e.g. "is this a fact or an instruction"): pick the single best-fitting category for the chunk and output that category as BOTH "mention" and "canonical", even if that exact word is not in the text. Output at most one entity of such a type per chunk.`,
+    "",
     "Rules:",
-    `- For each entity, output a "mention" (the exact surface form as it appears, in its original language) and a "canonical" name normalized to ${canonicalLanguage}.`,
+    "- A chunk can yield MULTIPLE entities \u2014 of the same named-entity type and of different types. Extract every distinct entity you find. The one-per-chunk limit applies ONLY to classification/property types.",
     `- The canonical name merges variants and translations: e.g. "M\xFCnchen" and "MUC" both canonicalize to the ${canonicalLanguage} form "Munich". "Acme Inc" and "ACME" both canonicalize to "Acme".`,
     "- DO NOT translate or alter identifiers, case numbers, SKUs, product codes, or proper product names \u2014 keep those verbatim as their own canonical.",
-    "- Only use the entity types listed above. Ignore anything that does not fit a listed type.",
-    "- Set chunkIndex to the index of the chunk the entity was found in.",
-    "- Return an empty array if no entities are present."
+    "- Only put entities of the listed types in the `entities` array. Do NOT put anything else there.",
+    "- Use an empty `entities` array when no listed type applies to the text.",
+    "",
+    `Separately, in "suggestedTypes", propose up to ${MAX_SUGGESTIONS} entity TYPES that recur in the text but are NOT in the list above and would be worth tracking (e.g. a kind of code, component, or product that keeps appearing). For each, give a concise name, a one-sentence description, and the full list of its "mentions" found in the chunks \u2014 extract those mentions exactly as you would for a configured named-entity type (each with its chunkIndex, the surface-form "mention", a normalized "canonical", and "confidence"). Leave the array empty if nothing stands out. Never put these in the "entities" array.`
   ].join("\n");
 };
 var buildUserPrompt = (chunks) => {
@@ -4602,13 +5764,17 @@ var extractEntitiesForItem = async ({
   chunks,
   types
 }) => {
-  if (!types.length || !chunks.length) return [];
-  const modelId = context.entities?.model || process.env.EXULU_ENTITY_EXTRACTION_MODEL;
+  const empty = {
+    mentions: [],
+    suggestions: []
+  };
+  if (!types.length || !chunks.length) return empty;
+  const { effectiveModel: modelId } = await resolveEntityModel(context);
   if (!modelId) {
     console.warn(
-      `[EXULU] Entity extraction skipped for context ${context.id}: no entities.model configured and EXULU_ENTITY_EXTRACTION_MODEL is unset.`
+      `[EXULU] Entity extraction skipped for context ${context.id}: no model configured. Select one in the Entities tab, set context.entities.model in code, or set EXULU_ENTITY_EXTRACTION_MODEL.`
     );
-    return [];
+    return empty;
   }
   const canonicalLanguage = context.entities?.canonicalLanguage || "english";
   const confidenceThreshold = context.entities?.confidenceThreshold ?? 0.5;
@@ -4625,15 +5791,15 @@ var extractEntitiesForItem = async ({
       `[EXULU] Entity extraction skipped for context ${context.id}: could not resolve model ${modelId}:`,
       err.message
     );
-    return [];
+    return empty;
   }
   const system = buildSystemPrompt(types, canonicalLanguage);
-  const validTypeNames = new Set(types.map((t) => t.name.toLowerCase().trim()));
   const batches = [];
   for (let i = 0; i < chunks.length; i += CHUNK_BATCH_SIZE) {
     batches.push(chunks.slice(i, i + CHUNK_BATCH_SIZE));
   }
   const mentions = [];
+  const suggestionsByName = /* @__PURE__ */ new Map();
   for (const batch of batches) {
     try {
       const { output } = await generateText2({
@@ -4647,16 +5813,47 @@ var extractEntitiesForItem = async ({
       for (const e of output.entities) {
         if (!e.mention || !e.canonical || !e.type) continue;
         if (e.confidence < confidenceThreshold) continue;
-        if (!validTypeNames.has(e.type.toLowerCase().trim())) continue;
-        const declared = types.find((t) => t.name.toLowerCase().trim() === e.type.toLowerCase().trim());
+        const eType = e.type.toLowerCase().trim();
+        const declared = types.find(
+          (t) => t.name.toLowerCase().trim() === eType || (t.description || "").toLowerCase().trim() === eType
+        );
+        if (!declared) continue;
         mentions.push({
           chunkIndex: e.chunkIndex,
-          type: declared?.name || e.type,
+          type: declared.name,
           mention: e.mention,
           canonical: e.canonical,
           confidence: e.confidence
         });
       }
+      for (const s of output.suggestedTypes ?? []) {
+        const name = (s?.name || "").trim();
+        if (!name) continue;
+        const key = name.toLowerCase();
+        const isConfigured = types.some(
+          (t) => t.name.toLowerCase().trim() === key || (t.description || "").toLowerCase().trim() === key
+        );
+        if (isConfigured) continue;
+        const sMentions = (s.mentions ?? []).filter(
+          (m) => m.mention && m.canonical && m.confidence >= confidenceThreshold
+        );
+        for (const m of sMentions) {
+          mentions.push({
+            chunkIndex: m.chunkIndex,
+            type: name,
+            mention: m.mention,
+            canonical: m.canonical,
+            confidence: m.confidence
+          });
+        }
+        if (!suggestionsByName.has(key)) {
+          suggestionsByName.set(key, {
+            name,
+            description: (s.description || "").trim(),
+            example: sMentions[0]?.mention || void 0
+          });
+        }
+      }
     } catch (err) {
       console.error(
         `[EXULU] Entity extraction batch failed for context ${context.id} (continuing):`,
@@ -4664,7 +5861,11 @@ var extractEntitiesForItem = async ({
       );
     }
   }
-  return mentions;
+  const suggestions = [...suggestionsByName.values()];
+  console.log(
+    `[EXULU][entities] context ${context.id}: kept ${mentions.length} mention(s), ${suggestions.length} suggestion(s).`
+  );
+  return { mentions, suggestions };
 };
 
 // src/exulu/entities/normalize.ts
@@ -4746,6 +5947,27 @@ var getEntityIdsForItem = async (context, itemId) => {
   const rows = await db2(junctionTable).where({ item_id: itemId }).distinct("entity_id");
   return rows.map((r) => r.entity_id);
 };
+var getEntitiesForItem = async (context, itemId) => {
+  if (!await chunkEntitiesTableExists(context)) return [];
+  const { db: db2 } = await postgresClient();
+  const junctionTable = getChunkEntitiesTableName(context.id);
+  const entitiesTable = getEntitiesTableName(context.id);
+  const rows = await db2(`${junctionTable} as j`).join(`${entitiesTable} as e`, "e.id", "j.entity_id").where("j.item_id", itemId).groupBy("e.id", "e.type", "e.display_name").select(
+    "e.id as id",
+    "e.type as type",
+    "e.display_name as name",
+    db2.raw("COUNT(*)::int as mentions")
+  ).orderBy([
+    { column: "e.type", order: "asc" },
+    { column: "e.display_name", order: "asc" }
+  ]);
+  return rows.map((r) => ({
+    id: r.id,
+    type: r.type,
+    name: r.name,
+    mentions: Number(r.mentions) || 0
+  }));
+};
 var ingestEntitiesForItem = async ({
   context,
   itemId,
@@ -4830,6 +6052,37 @@ var ingestEntitiesForItem = async ({
     });
   });
 };
+var detachEntitiesForItem = async (context, itemId) => {
+  if (!await chunkEntitiesTableExists(context)) return 0;
+  const { db: db2 } = await postgresClient();
+  const entitiesTable = getEntitiesTableName(context.id);
+  const junctionTable = getChunkEntitiesTableName(context.id);
+  const itemsTable = getTableName(context.id);
+  let detached = 0;
+  await db2.transaction(async (trx) => {
+    const affected = (await trx(junctionTable).where({ item_id: itemId }).distinct("entity_id")).map((r) => r.entity_id);
+    detached = affected.length;
+    if (!affected.length) return;
+    await trx(junctionTable).where({ item_id: itemId }).delete();
+    await trx(entitiesTable).whereIn("id", affected).update({ mention_count: 0, doc_count: 0 });
+    const placeholders = affected.map(() => "?").join(",");
+    await trx.raw(
+      `UPDATE ${entitiesTable} e
+       SET mention_count = sub.mc, doc_count = sub.dc
+       FROM (
+         SELECT entity_id, COUNT(*)::int AS mc, COUNT(DISTINCT item_id)::int AS dc
+         FROM ${junctionTable}
+         WHERE entity_id IN (${placeholders})
+         GROUP BY entity_id
+       ) sub
+       WHERE e.id = sub.entity_id`,
+      affected
+    );
+    await trx(entitiesTable).whereIn("id", affected).where({ mention_count: 0 }).delete();
+    await trx(itemsTable).where({ id: itemId }).update({ entities_updated_at: (/* @__PURE__ */ new Date()).toISOString(), entity_types_signature: null });
+  });
+  return detached;
+};
 var resolveQueryEntities = async (context, mentions) => {
   if (!mentions.length) return [];
   const { db: db2 } = await postgresClient();
@@ -4961,22 +6214,31 @@ var extractAndIngestEntities = async ({
 }) => {
   try {
     const types = await hydrateEntityTypes(context);
-    if (!types.length || !context.embedder) return;
+    if (!types.length || !context.embedder) return 0;
     await ensureEntityTables(context);
     const { db: db2 } = await postgresClient();
     const chunkRows = await db2(getChunksTableName(context.id)).where({ source: itemId }).select("chunk_index", "content").orderBy("chunk_index", "asc");
     const chunks = chunkRows.map((c) => ({ index: Number(c.chunk_index), content: c.content })).filter((c) => c.content);
-    const mentions = await extractEntitiesForItem({ context, chunks, types });
+    const { mentions, suggestions } = await extractEntitiesForItem({
+      context,
+      chunks,
+      types
+    });
     const signature = computeTypesSignature(types);
     await ingestEntitiesForItem({ context, itemId, mentions, signature, previousEntityIds });
+    if (suggestions.length) {
+      await upsertEntitySuggestions(context, suggestions);
+    }
     console.log(
       `[EXULU] Entity ingestion complete for item ${itemId} in context ${context.id}: ${mentions.length} mentions.`
     );
+    return mentions.length;
   } catch (err) {
     console.error(
       `[EXULU] Entity ingestion failed for item ${itemId} in context ${context.id} (non-fatal):`,
       err.message
     );
+    return 0;
   }
 };
 
@@ -4997,7 +6259,8 @@ var vectorSearch = async ({
   trigger,
   cutoffs,
   expand,
-  entityFilter
+  entityFilter,
+  queryEmbedding
 }) => {
   const table = convertContextToTableDefinition(context);
   console.log("[EXULU] Called vector search.", {
@@ -5079,29 +6342,53 @@ var vectorSearch = async ({
   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;
     }
-    const result = await embedder.generateFromQuery(
-      context.id,
-      query,
-      {
+    if (queryEmbedding && queryEmbedding.length) {
+      vector = queryEmbedding;
+      _embedSource = "reused";
+    } else {
+      const _ts = Date.now();
+      await updateStatistic({
+        name: "count",
         label: table.name.singular,
-        trigger
-      },
-      user?.id,
-      role
-    );
-    if (!result?.chunks?.[0]?.vector) {
-      throw new Error("No vector generated for query.");
+        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 = result.chunks[0].vector;
     vectorStr = `ARRAY[${vector.join(",")}]`;
     vectorExpr = `${vectorStr}::vector`;
   }
@@ -5128,6 +6415,7 @@ var vectorSearch = async ({
   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);
@@ -5241,6 +6529,11 @@ var vectorSearch = async ({
       ]).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,
@@ -5289,7 +6582,7 @@ var vectorSearch = async ({
   if (entitiesOn && rawQuery) {
     try {
       const types = await hydrateEntityTypes(context);
-      const queryMentions = await extractEntitiesForItem({
+      const { mentions: queryMentions } = await extractEntitiesForItem({
         context,
         chunks: [{ index: 0, content: rawQuery }],
         types
@@ -5328,7 +6621,6 @@ var vectorSearch = async ({
           { length: expand.before },
           (_, i) => chunk.chunk_index - expand.before + i
         ).filter((index) => index >= 0);
-        console.log("[EXULU] Indices to fetch:", indicesToFetch);
         await Promise.all(
           indicesToFetch.map(async (index) => {
             if (expandedMap.has(`${chunk.item_id}-${index}`)) {
@@ -5373,7 +6665,6 @@ var vectorSearch = async ({
           { length: expand.after },
           (_, i) => chunk.chunk_index + i + 1
         );
-        console.log("[EXULU] Indices to fetch:", indicesToFetch);
         await Promise.all(
           indicesToFetch.map(async (index) => {
             if (expandedMap.has(`${chunk.item_id}-${index}`)) {
@@ -5449,7 +6740,7 @@ var vectorSearch = async ({
     context: {
       name: table.name.singular,
       id: table.id || "",
-      embedder: embedder.name
+      embedder: embedder.model
     },
     chunks: results,
     entityInsights
@@ -5681,12 +6972,6 @@ var bullmqDecorator = async ({
 };
 
 // src/exulu/context.ts
-var getTableName = (id) => {
-  return sanitizeName(id) + "_items";
-};
-var getChunksTableName = (id) => {
-  return sanitizeName(id) + "_chunks";
-};
 var 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.
@@ -5698,6 +6983,12 @@ var ExuluContext2 = class {
   processor;
   description;
   embedder;
+  /**
+   * Splits an item into embeddable chunks. Moved here from the removed
+   * ExuluEmbedder. When omitted, the built-in `defaultChunker` (SentenceChunker)
+   * is used so a context works from just an embedder model name.
+   */
+  chunker;
   queryRewriter;
   resultReranker;
   configuration;
@@ -5713,6 +7004,7 @@ var ExuluContext2 = class {
     name,
     description,
     embedder,
+    chunker,
     processor,
     active,
     fields,
@@ -5744,6 +7036,7 @@ var ExuluContext2 = class {
     };
     this.description = description;
     this.embedder = embedder;
+    this.chunker = chunker;
     this.active = active;
     this.queryRewriter = queryRewriter;
     this.resultReranker = resultReranker;
@@ -5904,20 +7197,40 @@ var ExuluContext2 = class {
       throw new Error("Item id is required for generating embeddings.");
     }
     const { db: db2 } = await postgresClient();
-    const { id: source, chunks } = await this.embedder.generateFromDocument(
-      this.id,
-      {
-        ...item,
-        id: item.id
-      },
-      config,
-      {
-        label: statistics?.label || this.name,
-        trigger: statistics?.trigger || "agent"
-      },
-      user,
-      role
+    if (statistics) {
+      await updateStatistic({
+        name: "count",
+        label: statistics.label,
+        type: STATISTICS_TYPE_ENUM.EMBEDDER_GENERATE,
+        trigger: statistics.trigger,
+        count: 1,
+        user,
+        role
+      });
+    }
+    const source = item.id;
+    const resolved = await resolveEmbedder({
+      model: this.embedder.model,
+      contextId: this.id,
+      contextName: this.name,
+      userId: user,
+      roleId: role
+    });
+    const chunkerFn = this.chunker ?? defaultChunker;
+    const { chunks: produced } = await chunkerFn(
+      { ...item, id: item.id },
+      resolved.maxChunkSize,
+      { storage: new ExuluStorage({ config }) }
     );
+    console.log("[EXULU] Generating embeddings.");
+    const contents = produced.map((c) => c.content);
+    const vectors = contents.length ? await resolved.embed(contents, { inputType: "document" }) : [];
+    const chunks = produced.map((c, i) => ({
+      content: c.content,
+      index: c.index,
+      metadata: c.metadata ?? {},
+      vector: vectors[i] ?? []
+    }));
     const previousEntityIds = await captureEntitiesBeforeReembed(this, item.id);
     await db2.from(getChunksTableName(this.id)).where({ source }).delete();
     if (chunks?.length) {
@@ -6152,12 +7465,18 @@ var ExuluContext2 = class {
   };
   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;
   };
@@ -6188,8 +7507,8 @@ var ExuluContext2 = class {
           console.log("[EXULU] embedder is in queue mode, scheduling job.");
           const job = await bullmqDecorator({
             timeoutInSeconds: queue.timeoutInSeconds || 180,
-            label: `${this.embedder.name}`,
-            embedder: this.embedder.id,
+            label: `${this.embedder.model}`,
+            embedder: this.embedder.model,
             context: this.id,
             backoff: queue.backoff || {
               type: "exponential",
@@ -6214,7 +7533,7 @@ var ExuluContext2 = class {
           config,
           user,
           {
-            label: this.embedder.name,
+            label: this.embedder.model,
             trigger: trigger || "agent"
           },
           role,
@@ -6320,6 +7639,25 @@ var ExuluContext2 = class {
       }
       return { processed: batch.length, skipped };
     },
+    /**
+     * Extract + ingest entities for a SINGLE item — powers the item detail
+     * page's "Extract entities" test action. Returns the number of mentions
+     * found so the UI can report the result.
+     */
+    extractItem: async (itemId) => {
+      if (!await entitiesEnabled(this)) {
+        throw new Error(
+          "Entity extraction is not configured for this context (no entity types, or no embedder)."
+        );
+      }
+      const extracted = await extractAndIngestEntities({ context: this, itemId });
+      return { extracted };
+    },
+    /** Detach all entities from a single item (drops links, prunes orphans). */
+    detachItem: async (itemId) => {
+      const detached = await detachEntitiesForItem(this, itemId);
+      return { detached };
+    },
     /** Remove all entities (and their mentions via cascade) of a given type. */
     purgeType: async (typeName) => {
       if (!await entitiesTableExists(this)) return { removed: 0 };
@@ -6374,18 +7712,19 @@ var ExuluContext2 = class {
     const { db: db2 } = await postgresClient();
     const tableName = getChunksTableName(this.id);
     console.log("[EXULU] Creating table: " + tableName);
+    if (!this.embedder) {
+      throw new Error(
+        "Embedder must be set for context " + this.name + " to create chunks table."
+      );
+    }
+    const { dimensionality } = getEmbeddingModelInfo(this.embedder.model);
     await db2.schema.createTable(tableName, (table) => {
-      if (!this.embedder) {
-        throw new Error(
-          "Embedder must be set for context " + this.name + " to create chunks table."
-        );
-      }
       table.uuid("id").primary().defaultTo(db2.fn.uuid());
       table.uuid("source").references("id").inTable(getTableName(this.id));
       table.text("content");
       table.jsonb("metadata");
       table.integer("chunk_index");
-      table.specificType("embedding", `vector(${this.embedder.vectorDimensions})`);
+      table.specificType("embedding", `vector(${dimensionality})`);
       const languages = this.configuration.languages?.length ? this.configuration.languages : ["english"];
       const tsvectorExpression = languages.map((lang) => `to_tsvector('${lang}', coalesce(content, ''))`).join(" || ");
       table.specificType(
@@ -7043,16 +8382,16 @@ async function createDynamicTools(chunks, hadExcludedContent) {
 }
 
 // ee/agentic-retrieval/v3/session-tools-registry.ts
-var registry2 = /* @__PURE__ */ new Map();
+var registry3 = /* @__PURE__ */ new Map();
 function registerSessionTools(sessionId, tools) {
-  const existing = registry2.get(sessionId) ?? /* @__PURE__ */ new Map();
+  const existing = registry3.get(sessionId) ?? /* @__PURE__ */ new Map();
   for (const [name, toolDef] of Object.entries(tools)) {
     existing.set(name, toolDef);
   }
-  registry2.set(sessionId, existing);
+  registry3.set(sessionId, existing);
 }
 function getSessionTools(sessionId) {
-  const toolMap = registry2.get(sessionId);
+  const toolMap = registry3.get(sessionId);
   if (!toolMap || toolMap.size === 0) return {};
   return Object.fromEntries(toolMap.entries());
 }
@@ -7162,8 +8501,8 @@ ${customInstructions}` : ""
       (tc) => tc.toolName === "search_content" && tc.input?.includeContent === false || tc.toolName === "search_items_by_name"
     );
     if (reranker && stepChunks.length > 0) {
-      console.log(`[EXULU] v3 reranking ${stepChunks.length} chunks with ${reranker.name}`);
-      stepChunks = await reranker.run(query, stepChunks);
+      console.log(`[EXULU] v3 reranking ${stepChunks.length} chunks with ${reranker.model}`);
+      stepChunks = await reranker.rerank(query, stepChunks);
     }
     const newDynamic = await createDynamicTools(stepChunks, hadExcludedContent);
     Object.assign(dynamicTools, newDynamic);
@@ -7251,7 +8590,7 @@ ${customInstructions}` : ""
 }
 
 // ee/agentic-retrieval/v3/trajectory.ts
-import * as fs from "fs/promises";
+import * as fs2 from "fs/promises";
 import * as path from "path";
 var trajectoryRegistry = {
   lastFile: void 0
@@ -7452,13 +8791,13 @@ var TrajectoryLogger = class {
     };
     if (!writeFiles) return void 0;
     try {
-      await fs.mkdir(this.logDir, { recursive: true });
+      await fs2.mkdir(this.logDir, { recursive: true });
       const ts = Date.now();
       const jsonPath = path.join(this.logDir, `trajectory_${ts}.json`);
       const mdPath = path.join(this.logDir, `trajectory_${ts}.md`);
       await Promise.all([
-        fs.writeFile(jsonPath, JSON.stringify(this.data, null, 2), "utf-8"),
-        fs.writeFile(mdPath, this.toMarkdown(durationMs, success, error), "utf-8")
+        fs2.writeFile(jsonPath, JSON.stringify(this.data, null, 2), "utf-8"),
+        fs2.writeFile(mdPath, this.toMarkdown(durationMs, success, error), "utf-8")
       ]);
       console.log(`[EXULU] v3 trajectory saved: trajectory_${ts}.json + trajectory_${ts}.md`);
       trajectoryRegistry.lastFile = jsonPath;
@@ -7626,7 +8965,6 @@ SCOPE CONSTRAINT: Retrieval is scoped to preselected items/contexts. Per context
 function createAgenticRetrievalToolV3({
   contexts,
   instructions: adminInstructions,
-  rerankers,
   user,
   role,
   model,
@@ -7761,7 +9099,18 @@ function createAgenticRetrievalToolV3({
         requiresPreselectedContexts = toolVariablesConfig["require_preselected_contexts"] === true || toolVariablesConfig["require_preselected_contexts"] === "true";
         const rerankerId = toolVariablesConfig["reranker"];
         if (rerankerId && rerankerId !== "none") {
-          configuredReranker = rerankers.find((r) => r.id === rerankerId);
+          try {
+            configuredReranker = await resolveReranker({
+              model: rerankerId,
+              user,
+              roleId: role
+            });
+          } catch (err) {
+            console.warn(
+              `[EXULU] v3 \u2014 could not resolve reranker "${rerankerId}", continuing without reranking:`,
+              err
+            );
+          }
         }
       }
       console.log("[EXULU] Managed context enabled:", managedContextEnabled);
@@ -7844,9 +9193,21 @@ var createNewMemoryItemTool = (agent, context) => {
       case "longText":
       case "shortText":
       case "code":
-      case "enum":
         fields[field.name] = z10.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] = z10.preprocess(
+            (v) => typeof v === "string" ? v.toUpperCase() : v,
+            z10.enum(enumValues)
+          ).describe(
+            "The " + field.name + " of the item to create. Must be one of: " + field.enumValues.join(", ")
+          );
+        } else {
+          fields[field.name] = z10.string().describe("The " + field.name + " of the item to create");
+        }
+        break;
       case "json":
         fields[field.name] = z10.string({}).describe(
           "The " + field.name + " of the item to create, it should be a valid JSON string."
@@ -7872,6 +9233,9 @@ var createNewMemoryItemTool = (agent, context) => {
         break;
     }
   }
+  fields["visibility"] = z10.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,
@@ -7881,14 +9245,36 @@ var createNewMemoryItemTool = (agent, context) => {
     type: "function",
     inputSchema: z10.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,
@@ -7926,14 +9312,14 @@ import {
   SandboxManager
 } from "@anthropic-ai/sandbox-runtime";
 import { mkdir as mkdir2, rm, writeFile as writeFile2, readFile as fsReadFile, readdir, stat } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
-import { join as join3, dirname, resolve as resolve2, relative, posix } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { join as join3, dirname, resolve as resolve3, relative, posix } from "path";
 import { exec as exec2, spawn as spawn2 } from "child_process";
 import { promisify as promisify2 } from "util";
 
 // src/exulu/system-dependencies.ts
 import { exec } from "child_process";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { join as join2 } from "path";
 import { promisify } from "util";
 var execAsync = promisify(exec);
@@ -7999,7 +9385,7 @@ async function probeDependency(dep) {
     case "npm-global": {
       const root = await getNpmGlobalRoot();
       if (!root) return false;
-      return existsSync2(join2(root, dep.check.packageName));
+      return existsSync3(join2(root, dep.check.packageName));
     }
   }
 }
@@ -8078,18 +9464,18 @@ function probeSandboxSupport() {
     if (process.platform !== "linux") {
       return { canSandbox: false, reason: `Unsupported platform: ${process.platform}` };
     }
-    return await new Promise((resolve3) => {
+    return await new Promise((resolve4) => {
       const child = spawn2("bwrap", ["--dev-bind", "/", "/", "--", "/bin/true"]);
       let stderr = "";
       child.stderr.on("data", (chunk) => {
         stderr += chunk.toString();
       });
       child.on("error", (err) => {
-        resolve3({ canSandbox: false, reason: `bwrap not executable: ${err.message}` });
+        resolve4({ canSandbox: false, reason: `bwrap not executable: ${err.message}` });
       });
       child.on("exit", (code) => {
-        if (code === 0) resolve3({ canSandbox: true });
-        else resolve3({ canSandbox: false, reason: stderr.trim() || `bwrap exited ${code}` });
+        if (code === 0) resolve4({ canSandbox: true });
+        else resolve4({ canSandbox: false, reason: stderr.trim() || `bwrap exited ${code}` });
       });
     });
   })();
@@ -8135,7 +9521,7 @@ async function downloadSkill(skill, skillsDirectory, config) {
   }
 }
 function isArtifactPath(absPath, sessionDir) {
-  const resolved = resolve2(absPath);
+  const resolved = resolve3(absPath);
   const rel = relative(sessionDir, resolved);
   if (!rel || rel.startsWith("..")) return false;
   const first = rel.split("/")[0];
@@ -8194,7 +9580,7 @@ async function restoreArtifactsFromS3(sessionDir, sessionId, userId, config) {
 async function downloadKeyIntoSandbox(opts) {
   const { sessionId, userId, fullS3Key, config } = opts;
   const sessionDir = join3("/tmp", "exulu-sessions", sessionId);
-  if (!existsSync3(sessionDir)) {
+  if (!existsSync4(sessionDir)) {
     return { written: false };
   }
   const userPrefix = `user_${userId}/sessions/${sessionId}/`;
@@ -8228,7 +9614,7 @@ async function createSessionSandbox(sessionId, skills, config, userId) {
     return cached.handle;
   }
   const sessionDir = join3("/tmp", "exulu-sessions", sessionId);
-  const dirExisted = existsSync3(sessionDir);
+  const dirExisted = existsSync4(sessionDir);
   await mkdir2(sessionDir, { recursive: true });
   const skillsDirectory = join3(sessionDir, "skills");
   const installedSkills = /* @__PURE__ */ new Map();
@@ -8355,7 +9741,7 @@ Probe error: ${probe.reason ?? "(no detail)"}`
     if (!persistenceEnabled || !isArtifactPath(absPath, sessionDir)) {
       return {};
     }
-    const rel = relative(sessionDir, resolve2(absPath));
+    const rel = relative(sessionDir, resolve3(absPath));
     const s3Key = artifactS3Key(sessionId, rel);
     const out = {};
     try {
@@ -8647,7 +10033,7 @@ var hydrateVariables = async (tool6) => {
   await Promise.all(promises);
   return tool6;
 };
-var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, providerapikey, contexts, rerankers, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems) => {
+var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, providerapikey, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems) => {
   if (!currentTools) return {};
   if (!allExuluTools) {
     allExuluTools = [];
@@ -8656,7 +10042,7 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
     contexts = [];
   }
   let sharedSessionSandbox;
-  if (sessionID && exuluConfig) {
+  if (sessionID && exuluConfig && agent?.sandbox_enabled === true) {
     try {
       sharedSessionSandbox = await createSessionSandbox(
         sessionID,
@@ -8715,7 +10101,6 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
     const agenticSearchTool = createAgenticRetrievalToolV3({
       contexts: contexts.filter((context) => context.id !== agent?.memory),
       // dont include the agents memory in the agentic search tool!
-      rerankers: rerankers || [],
       user,
       role: user?.role?.id,
       model,
@@ -8911,6 +10296,7 @@ export {
   postgresClient,
   authentication,
   STATISTICS_TYPE_ENUM,
+  resolveLiteLLMConfigPath,
   getPresignedUrl,
   uploadFile,
   listS3ObjectsByPrefix,
@@ -8923,17 +10309,17 @@ export {
   createUppyRoutes,
   ExuluStorage,
   sanitizeName,
-  applySorting,
-  applyAccessControl,
-  applyFilters,
-  checkLicense,
-  coreSchemas,
-  convertContextToTableDefinition,
-  updateStatistic,
-  checkRecordAccess,
+  getTableName,
+  getChunksTableName,
+  ExuluTokenizer,
+  Chunk,
+  BaseChunker,
+  SentenceChunker,
+  defaultChunker,
   LITELLM_UI_PATH,
   isLiteLLMEnabled,
   setLiteLLMPackageRoot,
+  enableLiteLLMClientMode,
   startLiteLLMSupervisor,
   waitForLiteLLMReady,
   buildTags,
@@ -8951,16 +10337,29 @@ export {
   getTagBudgetMap,
   provisionDefaultUserBudget,
   getUserBudgetView,
+  resolveEmbedder,
+  updateStatistic,
+  applySorting,
+  applyAccessControl,
+  applyFilters,
+  checkLicense,
+  coreSchemas,
+  convertContextToTableDefinition,
+  setEntityModelSetting,
+  resolveEntityModel,
+  checkRecordAccess,
   ResolveModelError,
   resolveModel,
   exuluApp,
+  getEntitiesTableName,
+  getChunkEntitiesTableName,
+  getEntitiesForItem,
   ensureEntityTables,
   vectorSearch,
   mapType,
   maybePruneJobResults,
-  getTableName,
-  getChunksTableName,
   ExuluContext2 as ExuluContext,
+  resolveReranker,
   oauthRegistry,
   oauthTokenStore,
   OAUTH_CALLBACK_PATH,