@infuro/cms-core 1.0.19 → 1.0.20

package/dist/api.js

@@ -1,4 +1,5 @@
 var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
@@ -7,6 +8,14 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
 
 // src/plugins/erp/erp-queue.ts
 async function queueErp(cms, payload) {
@@ -1335,6 +1344,86 @@ async function assertCaptchaOk(getCms, body, req, json) {
   return json({ error: result.message }, { status: result.status });
 }
 
+// src/entities/llm-agent.entity.ts
+import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
+var LlmAgent = class {
+  id;
+  name;
+  slug;
+  systemInstruction;
+  model;
+  temperature;
+  maxTokens;
+  validationRules;
+  enabled;
+  createdAt;
+  updatedAt;
+  deletedAt;
+  deleted;
+  createdBy;
+  updatedBy;
+  deletedBy;
+};
+__decorateClass([
+  PrimaryGeneratedColumn()
+], LlmAgent.prototype, "id", 2);
+__decorateClass([
+  Column("varchar")
+], LlmAgent.prototype, "name", 2);
+__decorateClass([
+  Column("varchar")
+], LlmAgent.prototype, "slug", 2);
+__decorateClass([
+  Column("text", { name: "system_instruction", default: "" })
+], LlmAgent.prototype, "systemInstruction", 2);
+__decorateClass([
+  Column("varchar", { nullable: true })
+], LlmAgent.prototype, "model", 2);
+__decorateClass([
+  Column("double precision", { name: "temperature", nullable: true })
+], LlmAgent.prototype, "temperature", 2);
+__decorateClass([
+  Column("int", { name: "max_tokens", nullable: true })
+], LlmAgent.prototype, "maxTokens", 2);
+__decorateClass([
+  Column("text", { name: "validation_rules", nullable: true })
+], LlmAgent.prototype, "validationRules", 2);
+__decorateClass([
+  Column("boolean", { default: true })
+], LlmAgent.prototype, "enabled", 2);
+__decorateClass([
+  Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
+], LlmAgent.prototype, "createdAt", 2);
+__decorateClass([
+  Column({ type: "timestamp", default: () => "CURRENT_TIMESTAMP" })
+], LlmAgent.prototype, "updatedAt", 2);
+__decorateClass([
+  Column({ type: "timestamp", nullable: true })
+], LlmAgent.prototype, "deletedAt", 2);
+__decorateClass([
+  Column("boolean", { default: false })
+], LlmAgent.prototype, "deleted", 2);
+__decorateClass([
+  Column("int", { nullable: true })
+], LlmAgent.prototype, "createdBy", 2);
+__decorateClass([
+  Column("int", { nullable: true })
+], LlmAgent.prototype, "updatedBy", 2);
+__decorateClass([
+  Column("int", { nullable: true })
+], LlmAgent.prototype, "deletedBy", 2);
+LlmAgent = __decorateClass([
+  Entity("llm_agents")
+], LlmAgent);
+function llmAgentToChatAgentOptions(agent) {
+  return {
+    systemPrompt: agent.systemInstruction?.trim() || void 0,
+    model: agent.model?.trim() || void 0,
+    temperature: agent.temperature ?? void 0,
+    max_tokens: agent.maxTokens ?? void 0
+  };
+}
+
 // src/lib/media-folder-path.ts
 function sanitizeMediaFolderPath(input) {
   if (input == null) return "";
@@ -1524,6 +1613,82 @@ async function extractZipMediaIntoParentTree(opts) {
 }
 
 // src/api/cms-handlers.ts
+function historyBeforeCurrentUser(history, currentUserContent) {
+  const last = history[history.length - 1];
+  if (last?.role === "user" && last.content === currentUserContent) {
+    return history.slice(0, -1);
+  }
+  return [...history];
+}
+function pickStructuredRules(rules) {
+  return {
+    maxUserChars: rules.maxUserChars,
+    maxMessageLength: rules.maxMessageLength,
+    minUserChars: rules.minUserChars,
+    minMessageLength: rules.minMessageLength,
+    blockedSubstrings: rules.blockedSubstrings
+  };
+}
+function guardrailsTextFromJsonObject(rules) {
+  const g = typeof rules.guardrails === "string" && rules.guardrails.trim() || typeof rules.outputRules === "string" && rules.outputRules.trim() || typeof rules.outputInstructions === "string" && rules.outputInstructions.trim() || "";
+  return g || null;
+}
+function parseLlmAgentValidationRules(validationRulesText) {
+  const raw = validationRulesText?.trim();
+  if (!raw) return { structured: {}, guardrailsForPrompt: null };
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "string") {
+      const s = parsed.trim();
+      return { structured: {}, guardrailsForPrompt: s || null };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { structured: {}, guardrailsForPrompt: raw };
+    }
+    const rules = parsed;
+    return {
+      structured: pickStructuredRules(rules),
+      guardrailsForPrompt: guardrailsTextFromJsonObject(rules)
+    };
+  } catch {
+    return { structured: {}, guardrailsForPrompt: raw };
+  }
+}
+function validateUserMessageAgainstStructuredRules(message, structured) {
+  const maxLen = structured.maxUserChars ?? structured.maxMessageLength;
+  if (typeof maxLen === "number" && Number.isFinite(maxLen) && maxLen >= 0 && message.length > maxLen) {
+    return { ok: false, error: `Message exceeds maximum length (${maxLen} characters)` };
+  }
+  const minLen = structured.minUserChars ?? structured.minMessageLength;
+  if (typeof minLen === "number" && Number.isFinite(minLen) && minLen > 0 && message.length < minLen) {
+    return { ok: false, error: `Message is shorter than minimum length (${minLen} characters)` };
+  }
+  const blocked = structured.blockedSubstrings;
+  if (Array.isArray(blocked) && blocked.length > 0) {
+    const lower = message.toLowerCase();
+    for (const s of blocked) {
+      if (typeof s !== "string" || !s.trim()) continue;
+      if (lower.includes(s.toLowerCase())) {
+        return { ok: false, error: "Message contains disallowed content" };
+      }
+    }
+  }
+  return { ok: true };
+}
+function validateUserMessageAgainstAgentRules(message, validationRulesText) {
+  const { structured } = parseLlmAgentValidationRules(validationRulesText);
+  return validateUserMessageAgainstStructuredRules(message, structured);
+}
+function mergeGuardrailsIntoSystemPrompt(baseSystem, guardrailsForPrompt) {
+  const g = guardrailsForPrompt?.trim();
+  const b = (baseSystem ?? "").trim();
+  if (!g) return b;
+  const block = `### Output guardrails (follow in every reply)
+${g}`;
+  return b ? `${b}
+
+${block}` : block;
+}
 function createDashboardStatsHandler(config) {
   const { dataSource, entityMap, json, requireAuth, requirePermission, requireEntityPermission } = config;
   return async function GET(req) {
@@ -2605,9 +2770,24 @@ function createSettingsApiHandlers(config) {
 }
 var KB_CHUNK_LIMIT = 10;
 var KB_CONTEXT_MAX_CHARS = 4e3;
+var RAG_LOG = "[rag-context]";
 function getQueryTerms(message) {
   return message.replace(/[^\w\s]/g, " ").split(/\s+/).filter((w) => w.length > 2).slice(0, 6);
 }
+function normalizeChatModeSetting(raw) {
+  if (raw === "external" || raw === "llm") return raw;
+  return "whatsapp";
+}
+async function loadLlmSettingsMap(dataSource, entityMap) {
+  if (!entityMap.configs) return {};
+  const repo = dataSource.getRepository(entityMap.configs);
+  const rows = await repo.find({ where: { settings: "llm", deleted: false } });
+  const out = {};
+  for (const row of rows) {
+    out[row.key] = row.value;
+  }
+  return out;
+}
 function createChatHandlers(config) {
   const { dataSource, entityMap, json, getCms } = config;
   const contactRepo = () => dataSource.getRepository(entityMap.contacts);
@@ -2615,6 +2795,26 @@ function createChatHandlers(config) {
   const msgRepo = () => dataSource.getRepository(entityMap.chat_messages);
   const chunkRepo = () => dataSource.getRepository(entityMap.knowledge_base_chunks);
   return {
+    async publicConfig(_req) {
+      try {
+        const map = await loadLlmSettingsMap(dataSource, entityMap);
+        const mode = normalizeChatModeSetting(map.chatMode);
+        const body = {
+          enabled: map.enabled !== "false",
+          chatMode: mode,
+          agentSlug: mode === "llm" ? (map.attachedAgentSlug ?? "").trim() : "",
+          botName: map.botName ?? "",
+          icon: map.icon ?? "",
+          iconImageUrl: map.iconImageUrl ?? "",
+          iconBackgroundColor: map.iconBackgroundColor ?? "#6366f1",
+          headerColor: map.headerColor ?? "#6366f1",
+          whatsappPhone: map.whatsappPhone ?? ""
+        };
+        return json(body);
+      } catch {
+        return json({ error: "Failed to load chat config" }, { status: 500 });
+      }
+    },
     async identify(req) {
       try {
         const body = await req.json();
@@ -2662,20 +2862,78 @@ function createChatHandlers(config) {
           relations: ["messages"]
         });
         if (!conv) return json({ error: "Conversation not found" }, { status: 404 });
-        const msgRepoInst = msgRepo();
-        await msgRepoInst.save(msgRepoInst.create({ conversationId, role: "user", content: message }));
         const cms = await getCms();
         const llm = cms.getPlugin("llm");
         if (!llm?.chat) return json({ error: "LLM not configured" }, { status: 503 });
+        const llmSettings = await loadLlmSettingsMap(dataSource, entityMap);
+        const supportMode = normalizeChatModeSetting(llmSettings.chatMode);
+        let effectiveSlug = (body?.agentSlug ?? "").trim();
+        if (!effectiveSlug && supportMode === "llm" && entityMap.llm_agents) {
+          effectiveSlug = (llmSettings.attachedAgentSlug ?? "").trim();
+        }
+        let agentRow = null;
+        if (effectiveSlug) {
+          if (!entityMap.llm_agents) {
+            return json({ error: "LLM agents are not configured on this deployment" }, { status: 400 });
+          }
+          const agentRepo = dataSource.getRepository(
+            entityMap.llm_agents
+          );
+          agentRow = await agentRepo.findOne({
+            where: { slug: effectiveSlug, deleted: false, enabled: true }
+          });
+          if (!agentRow && (body?.agentSlug ?? "").trim()) {
+            return json({ error: "Agent not found or disabled", agentSlug: effectiveSlug }, { status: 404 });
+          }
+        }
+        console.info(RAG_LOG, "step 1 | resolve agent", {
+          agentSlug: effectiveSlug || "(none)",
+          agentFound: !!agentRow,
+          agentId: agentRow?.id ?? null
+        });
+        const parsedValidation = agentRow ? parseLlmAgentValidationRules(agentRow.validationRules) : { structured: {}, guardrailsForPrompt: null };
+        if (agentRow) {
+          const v = validateUserMessageAgainstStructuredRules(message, parsedValidation.structured);
+          if (!v.ok) return json({ error: v.error, reason: "validation_failed" }, { status: 400 });
+        }
+        let kbDocumentScope;
+        const Junction = entityMap.llm_agent_knowledge_documents;
+        if (agentRow && Junction) {
+          const linkRepo = dataSource.getRepository(Junction);
+          const links = await linkRepo.find({ where: { agentId: agentRow.id } });
+          const ids = [...new Set(links.map((l) => l.documentId))];
+          if (ids.length > 0) kbDocumentScope = ids;
+        }
+        console.info(RAG_LOG, "step 2 | knowledge scope", {
+          scopedDocumentIds: kbDocumentScope ?? "(all documents)",
+          documentCount: kbDocumentScope?.length ?? "all"
+        });
+        const msgRepoInst = msgRepo();
+        await msgRepoInst.save(msgRepoInst.create({ conversationId, role: "user", content: message }));
         let contextParts = [];
+        console.info(RAG_LOG, "step 3 | embed user query", {
+          messageChars: message.length,
+          embedAvailable: !!llm.embed
+        });
         const queryEmbedding = llm.embed ? await llm.embed(message) : null;
+        console.info(RAG_LOG, "step 4 | query embedding result", {
+          dimensions: queryEmbedding?.length ?? 0,
+          hasEmbedding: !!(queryEmbedding && queryEmbedding.length > 0)
+        });
         if (queryEmbedding && queryEmbedding.length > 0) {
           const vectorStr = "[" + queryEmbedding.join(",") + "]";
           try {
-            const rows = await dataSource.query(
+            const rows = kbDocumentScope?.length ? await dataSource.query(
+              `SELECT id, content FROM knowledge_base_chunks WHERE embedding IS NOT NULL AND "documentId" = ANY($3::int[]) ORDER BY embedding <=> $1::vector LIMIT $2`,
+              [vectorStr, KB_CHUNK_LIMIT, kbDocumentScope]
+            ) : await dataSource.query(
               `SELECT id, content FROM knowledge_base_chunks WHERE embedding IS NOT NULL ORDER BY embedding <=> $1::vector LIMIT $2`,
               [vectorStr, KB_CHUNK_LIMIT]
             );
+            console.info(RAG_LOG, "step 5 | vector search results", {
+              rowsReturned: rows.length,
+              chunkIds: rows.map((r) => r.id)
+            });
             let totalLen = 0;
             for (const r of rows) {
               const text = (r.content ?? "").trim();
@@ -2683,13 +2941,24 @@ function createChatHandlers(config) {
               contextParts.push(text);
               totalLen += text.length;
             }
-          } catch {
+            console.info(RAG_LOG, "step 5a | vector context selected", {
+              chunksUsed: contextParts.length,
+              totalChars: totalLen
+            });
+          } catch (vecErr) {
+            console.warn(RAG_LOG, "step 5 | vector search failed; falling back to keyword", {
+              err: vecErr instanceof Error ? vecErr.message : String(vecErr)
+            });
           }
         }
         if (contextParts.length === 0) {
           const terms = getQueryTerms(message);
+          console.info(RAG_LOG, "step 6 | keyword fallback", {
+            reason: !(queryEmbedding && queryEmbedding.length > 0) ? "no embedding" : "vector search returned nothing",
+            searchTerms: terms
+          });
           if (terms.length > 0) {
-            const conditions = terms.map((t) => ({ content: ILike2(`%${t}%`) }));
+            const conditions = kbDocumentScope?.length ? terms.map((t) => ({ content: ILike2(`%${t}%`), documentId: In(kbDocumentScope) })) : terms.map((t) => ({ content: ILike2(`%${t}%`) }));
             const chunks = await chunkRepo().find({
               where: conditions,
               take: KB_CHUNK_LIMIT,
@@ -2704,19 +2973,66 @@ function createChatHandlers(config) {
               contextParts.push(text);
               totalLen += text.length;
             }
+            console.info(RAG_LOG, "step 6a | keyword results", {
+              chunksFound: chunks.length,
+              chunksUsed: contextParts.length,
+              totalChars: totalLen
+            });
           }
         }
-        const history = (conv.messages ?? []).sort((a, b) => new Date(a.createdAt ?? 0).getTime() - new Date(b.createdAt ?? 0).getTime()).map((m) => ({ role: m.role, content: m.content }));
-        const systemContent = contextParts.length > 0 ? `Use the following context about the company and its products to answer. If the answer is not in the context, say so.
+        const historyRaw = (conv.messages ?? []).sort((a, b) => new Date(a.createdAt ?? 0).getTime() - new Date(b.createdAt ?? 0).getTime()).map((m) => ({ role: m.role, content: m.content }));
+        const history = historyBeforeCurrentUser(historyRaw, message);
+        let content;
+        const ragContext = contextParts.length > 0 ? contextParts.join("\n\n") : void 0;
+        console.info(RAG_LOG, "step 7 | final context", {
+          method: contextParts.length > 0 ? "rag" : "none",
+          contextChunks: contextParts.length,
+          contextChars: ragContext?.length ?? 0,
+          contextPreview: ragContext ? ragContext.slice(0, 200) + (ragContext.length > 200 ? "\u2026" : "") : "(no context)"
+        });
+        if (agentRow && llm.chatAgent) {
+          const fromAgent = llmAgentToChatAgentOptions(agentRow);
+          const systemPrompt = mergeGuardrailsIntoSystemPrompt(
+            fromAgent.systemPrompt,
+            parsedValidation.guardrailsForPrompt
+          );
+          const res = await llm.chatAgent({
+            ...fromAgent,
+            systemPrompt: systemPrompt || void 0,
+            context: ragContext,
+            history,
+            userPrompt: message
+          });
+          content = res.content;
+        } else {
+          const ragSystem = contextParts.length > 0 ? `Use the following context about the company and its products to answer. If the answer is not in the context, say so.
 
 Context:
-${contextParts.join("\n\n")}` : "You are a helpful assistant for the company. If you do not have specific information, say so.";
-        const messages = [
-          { role: "system", content: systemContent },
-          ...history,
-          { role: "user", content: message }
-        ];
-        const { content } = await llm.chat(messages);
+${contextParts.join("\n\n")}` : "";
+          const defaultSystem = "You are a helpful assistant for the company. If you do not have specific information, say so.";
+          let systemContent;
+          if (agentRow) {
+            const base = agentRow.systemInstruction?.trim() || "";
+            systemContent = mergeGuardrailsIntoSystemPrompt(
+              [base, ragSystem].filter(Boolean).join("\n\n") || defaultSystem,
+              parsedValidation.guardrailsForPrompt
+            );
+          } else {
+            systemContent = ragSystem || defaultSystem;
+          }
+          const messages = [
+            { role: "system", content: systemContent },
+            ...history,
+            { role: "user", content: message }
+          ];
+          const chatOpts = agentRow ? {
+            model: agentRow.model ?? void 0,
+            temperature: agentRow.temperature ?? void 0,
+            max_tokens: agentRow.maxTokens ?? void 0
+          } : {};
+          const res = await llm.chat(messages, chatOpts);
+          content = res.content;
+        }
         await msgRepoInst.save(msgRepoInst.create({ conversationId, role: "assistant", content }));
         return json({ content });
       } catch (err) {
@@ -2727,6 +3043,314 @@ ${contextParts.join("\n\n")}` : "You are a helpful assistant for the company. If
   };
 }
 
+// src/api/llm-agent-knowledge-handlers.ts
+import { In as In2 } from "typeorm";
+var INGEST_CHUNK_CHARS = 900;
+var MAX_CHUNKS_PER_UPLOAD = 400;
+var EMBED_CONCURRENCY = 5;
+var MAX_PDF_BYTES = 25 * 1024 * 1024;
+var TEXT_FILE_TYPES = /* @__PURE__ */ new Set(["text/plain", "text/markdown", "application/json"]);
+var KB_LOG = "[llm-agent-knowledge]";
+function llmEmbedDebug() {
+  const v = process.env.LLM_EMBED_DEBUG?.toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+function isPdfUpload(mime, fileName) {
+  if (mime === "application/pdf") return true;
+  const n = fileName.toLowerCase();
+  return n.endsWith(".pdf");
+}
+async function extractTextFromPdf(buffer) {
+  const pdfParse = await import("pdf-parse");
+  const data = await pdfParse(buffer);
+  return (data?.text ?? "").trim();
+}
+async function writeEmbeddingsConcurrent(dataSource, embed, chunks, concurrency) {
+  let next = 0;
+  let written = 0;
+  let failed = 0;
+  let skippedEmpty = 0;
+  async function worker() {
+    for (; ; ) {
+      const i = next++;
+      if (i >= chunks.length) return;
+      const c = chunks[i];
+      try {
+        const emb = await embed(c.content);
+        if (emb?.length) {
+          const vectorStr = "[" + emb.join(",") + "]";
+          await dataSource.query(
+            `UPDATE knowledge_base_chunks SET embedding = $1::vector WHERE id = $2`,
+            [vectorStr, c.id]
+          );
+          written++;
+        } else {
+          skippedEmpty++;
+          if (llmEmbedDebug()) {
+            console.warn(`${KB_LOG} embed() returned empty vector`, { chunkId: c.id });
+          }
+        }
+      } catch (err) {
+        failed++;
+        console.error(`${KB_LOG} embedding DB update failed`, {
+          chunkId: c.id,
+          err: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  }
+  const n = Math.max(1, Math.min(concurrency, chunks.length));
+  await Promise.all(Array.from({ length: n }, () => worker()));
+  const summary = {
+    chunkCount: chunks.length,
+    written,
+    failed,
+    skippedEmpty
+  };
+  if (skippedEmpty > 0 && written === 0) {
+    summary.hint = "embed() returned empty vectors \u2014 see [LLM embed] logs (often HTTP 404 on /v1/embeddings, or wrong response shape).";
+  }
+  console.error(`${KB_LOG} embedding pass finished`, summary);
+  return { written, failed };
+}
+function splitIntoChunks(text, maxLen) {
+  const t = text.trim();
+  if (!t) return [];
+  const chunks = [];
+  for (let i = 0; i < t.length; i += maxLen) {
+    chunks.push(t.slice(i, i + maxLen));
+  }
+  return chunks;
+}
+async function findAgentBySlug(dataSource, llmAgents, slug) {
+  const repo = dataSource.getRepository(llmAgents);
+  return repo.findOne({
+    where: { slug, deleted: false }
+  });
+}
+function createLlmAgentKnowledgeHandlers(config) {
+  const { dataSource, entityMap, getCms, json, requireAuth, requireEntityPermission } = config;
+  const kbDoc = entityMap.knowledge_base_documents;
+  const kbChunk = entityMap.knowledge_base_chunks;
+  const llmAgents = entityMap.llm_agents;
+  const junction = entityMap.llm_agent_knowledge_documents;
+  if (!kbDoc || !kbChunk || !llmAgents || !junction) {
+    return null;
+  }
+  async function gate(req, action) {
+    const a = await requireAuth(req);
+    if (a) return a;
+    if (requireEntityPermission) {
+      const pe = await requireEntityPermission(req, "llm_agents", action);
+      if (pe) return pe;
+    }
+    return null;
+  }
+  return {
+    async list(req, slug) {
+      const denied = await gate(req, "read");
+      if (denied) return denied;
+      try {
+        const agent = await findAgentBySlug(dataSource, llmAgents, slug);
+        if (!agent) return json({ error: "Agent not found" }, { status: 404 });
+        const linkRepo = dataSource.getRepository(junction);
+        const links = await linkRepo.find({ where: { agentId: agent.id } });
+        const docIds = [...new Set(links.map((l) => l.documentId))];
+        if (docIds.length === 0) return json({ documents: [] });
+        const docRepo = dataSource.getRepository(kbDoc);
+        const docs = await docRepo.find({ where: { id: In2(docIds) } });
+        const byId = new Map(docs.map((d) => [d.id, d]));
+        const documents = docIds.map((id) => {
+          const d = byId.get(id);
+          return d ? { id: d.id, name: d.name } : null;
+        }).filter(Boolean);
+        return json({ documents });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Failed to list knowledge";
+        return json({ error: msg }, { status: 500 });
+      }
+    },
+    async post(req, slug) {
+      const denied = await gate(req, "update");
+      if (denied) return denied;
+      try {
+        const agent = await findAgentBySlug(dataSource, llmAgents, slug);
+        if (!agent) return json({ error: "Agent not found" }, { status: 404 });
+        let name = "";
+        let text = "";
+        let sourceUrl = null;
+        let existingDocumentId = null;
+        const ct = req.headers.get("content-type") || "";
+        if (ct.includes("application/json")) {
+          const body = await req.json();
+          existingDocumentId = typeof body?.documentId === "number" && Number.isFinite(body.documentId) ? body.documentId : null;
+          name = (body?.name ?? "").trim();
+          text = (body?.text ?? "").trim();
+          sourceUrl = typeof body?.sourceUrl === "string" && body.sourceUrl.trim() ? body.sourceUrl.trim() : null;
+        } else if (ct.includes("multipart/form-data")) {
+          const form = await req.formData();
+          name = form.get("name")?.trim() ?? "";
+          text = form.get("text")?.trim() ?? "";
+          const file = form.get("file");
+          if (file && typeof file !== "string" && "arrayBuffer" in file) {
+            const f = file;
+            const mime = (f.type || "").split(";")[0].trim().toLowerCase();
+            const buf = Buffer.from(await f.arrayBuffer());
+            if (TEXT_FILE_TYPES.has(mime)) {
+              const decoded = buf.toString("utf8");
+              if (!text) text = decoded;
+            } else if (isPdfUpload(mime, f.name || "")) {
+              if (buf.length > MAX_PDF_BYTES) {
+                return json(
+                  { error: `PDF too large (max ${Math.floor(MAX_PDF_BYTES / (1024 * 1024))}MB)` },
+                  { status: 413 }
+                );
+              }
+              try {
+                const extracted = await extractTextFromPdf(buf);
+                if (!text) text = extracted;
+              } catch {
+                return json(
+                  { error: "Could not read PDF text (file may be encrypted, corrupt, or image-only)" },
+                  { status: 422 }
+                );
+              }
+            } else {
+              return json(
+                {
+                  error: "Unsupported file type; use text/plain, text/markdown, application/json, or application/pdf"
+                },
+                { status: 415 }
+              );
+            }
+            if (!name && f.name) name = f.name.replace(/\.[^/.]+$/, "") || f.name;
+          }
+        } else {
+          return json({ error: "Use application/json or multipart/form-data" }, { status: 400 });
+        }
+        const linkRepo = dataSource.getRepository(junction);
+        if (existingDocumentId != null) {
+          const docRepo2 = dataSource.getRepository(kbDoc);
+          const existing = await docRepo2.findOne({ where: { id: existingDocumentId } });
+          if (!existing) return json({ error: "documentId not found" }, { status: 404 });
+          const dup2 = await linkRepo.findOne({
+            where: { agentId: agent.id, documentId: existingDocumentId }
+          });
+          if (!dup2) {
+            await linkRepo.save(linkRepo.create({ agentId: agent.id, documentId: existingDocumentId }));
+          }
+          return json({ documentId: existingDocumentId, linked: true, created: false });
+        }
+        if (!text) return json({ error: "text or file with text content is required" }, { status: 400 });
+        if (!name) name = "Untitled";
+        const parts = splitIntoChunks(text, INGEST_CHUNK_CHARS);
+        if (parts.length === 0) {
+          return json({ error: "text or file with text content is required" }, { status: 400 });
+        }
+        if (parts.length > MAX_CHUNKS_PER_UPLOAD) {
+          return json(
+            {
+              error: `Document is too large for one upload (${parts.length} chunks; max ${MAX_CHUNKS_PER_UPLOAD}). Split into smaller files.`
+            },
+            { status: 413 }
+          );
+        }
+        const docRepo = dataSource.getRepository(kbDoc);
+        const chunkRepo = dataSource.getRepository(kbChunk);
+        const now = /* @__PURE__ */ new Date();
+        const doc = await docRepo.save(
+          docRepo.create({ name, content: text, sourceUrl, createdAt: now, updatedAt: now })
+        );
+        const docId = doc.id;
+        const chunkRows = parts.map(
+          (content, i) => chunkRepo.create({ documentId: docId, content, chunkIndex: i, createdAt: now })
+        );
+        const savedList = await chunkRepo.save(chunkRows);
+        const savedChunks = savedList.map(
+          (row, i) => ({
+            id: row.id,
+            content: parts[i]
+          })
+        );
+        const dup = await linkRepo.findOne({ where: { agentId: agent.id, documentId: docId } });
+        if (!dup) {
+          await linkRepo.save(linkRepo.create({ agentId: agent.id, documentId: docId }));
+        }
+        let embeddingsWritten = 0;
+        let embeddingsFailed = 0;
+        try {
+          const cms = await getCms();
+          const llm = cms.getPlugin("llm");
+          if (llm?.embed && savedChunks.length > 0) {
+            console.info(`${KB_LOG} starting embedding pass`, { slug, chunkCount: savedChunks.length });
+            const embedBound = (text2) => llm.embed(text2);
+            const { written, failed } = await writeEmbeddingsConcurrent(
+              dataSource,
+              embedBound,
+              savedChunks,
+              EMBED_CONCURRENCY
+            );
+            embeddingsWritten = written;
+            embeddingsFailed = failed;
+          } else {
+            console.error(`${KB_LOG} embeddings skipped`, {
+              slug,
+              hasLlmPlugin: !!llm,
+              hasEmbed: typeof llm?.embed === "function",
+              chunkCount: savedChunks.length,
+              hint: !llm || typeof llm.embed !== "function" ? "LLM plugin missing or no embed(); check LLM_GATEWAY_URL + LLM_API_KEY so llm plugin initializes." : void 0
+            });
+          }
+        } catch (embErr) {
+          const detail = embErr instanceof Error ? embErr.message : String(embErr);
+          console.error(`${KB_LOG} embedding step threw before/during batch`, { slug, detail, embErr });
+          return json(
+            {
+              documentId: docId,
+              chunkCount: savedChunks.length,
+              created: true,
+              linked: true,
+              embeddingsWritten: 0,
+              embeddingsFailed: savedChunks.length,
+              warning: "Document saved and linked; embedding step failed.",
+              detail
+            },
+            { status: 201 }
+          );
+        }
+        return json({
+          documentId: docId,
+          chunkCount: savedChunks.length,
+          created: true,
+          linked: true,
+          embeddingsWritten,
+          embeddingsFailed
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Failed to ingest knowledge";
+        const name = err instanceof Error ? err.name : "";
+        return json({ error: msg, errorName: name || void 0 }, { status: 500 });
+      }
+    },
+    async unlink(req, slug, documentIdStr) {
+      const denied = await gate(req, "update");
+      if (denied) return denied;
+      const documentId = parseInt(documentIdStr, 10);
+      if (!Number.isFinite(documentId)) return json({ error: "Invalid document id" }, { status: 400 });
+      try {
+        const agent = await findAgentBySlug(dataSource, llmAgents, slug);
+        if (!agent) return json({ error: "Agent not found" }, { status: 404 });
+        const linkRepo = dataSource.getRepository(junction);
+        await linkRepo.delete({ agentId: agent.id, documentId });
+        return json({ ok: true });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Failed to unlink";
+        return json({ error: msg }, { status: 500 });
+      }
+    }
+  };
+}
+
 // src/message-templates/sms-defaults.ts
 var SMS_MESSAGE_TEMPLATE_DEFAULTS = [
   {
@@ -3035,6 +3659,26 @@ function createAdminRolesHandlers(config) {
 }
 
 // src/api/cms-api-handler.ts
+var KNOWLEDGE_SUFFIX = "knowledge";
+function matchLlmAgentKnowledgeRoute(path) {
+  const p = path[0] === "api" ? path.slice(1) : path;
+  if (p[0] !== "llm_agents" || p.length < 2) return null;
+  const seg1 = p[1];
+  if (!seg1) return null;
+  if (p[2] === KNOWLEDGE_SUFFIX) {
+    return {
+      slug: seg1,
+      documentId: p.length >= 4 ? p[3] : void 0
+    };
+  }
+  if (seg1.endsWith(KNOWLEDGE_SUFFIX) && seg1.length > KNOWLEDGE_SUFFIX.length) {
+    const slug = seg1.slice(0, -KNOWLEDGE_SUFFIX.length);
+    if (!slug) return null;
+    if (p.length === 2) return { slug, documentId: void 0 };
+    if (p.length === 3) return { slug, documentId: p[2] };
+  }
+  return null;
+}
 var DEFAULT_EXCLUDE = /* @__PURE__ */ new Set([
   "users",
   "password_reset_tokens",
@@ -3047,7 +3691,8 @@ var DEFAULT_EXCLUDE = /* @__PURE__ */ new Set([
   "cart_items",
   "wishlists",
   "wishlist_items",
-  "message_templates"
+  "message_templates",
+  "llm_agent_knowledge_documents"
 ]);
 function createCmsApiHandler(config) {
   const {
@@ -3071,6 +3716,7 @@ function createCmsApiHandler(config) {
     userProfile,
     settings: settingsConfig,
     chat: chatConfig,
+    llmAgentKnowledge: llmAgentKnowledgeConfig,
     requireEntityPermission: userRequireEntityPermission,
     getSessionUser
   } = config;
@@ -3178,6 +3824,17 @@ function createCmsApiHandler(config) {
     requireEntityPermission: requireEntityPermissionEffective
   });
   const chatHandlers = chatConfig ? createChatHandlers(chatConfig) : null;
+  const llmAgentKnowledgeMerged = llmAgentKnowledgeConfig ?? (chatConfig ? {
+    dataSource: chatConfig.dataSource,
+    entityMap: chatConfig.entityMap,
+    getCms: chatConfig.getCms,
+    json: chatConfig.json,
+    requireAuth: chatConfig.requireAuth
+  } : void 0);
+  const llmAgentKnowledgeHandlers = llmAgentKnowledgeMerged ? createLlmAgentKnowledgeHandlers({
+    ...llmAgentKnowledgeMerged,
+    requireEntityPermission: requireEntityPermissionEffective
+  }) : null;
   function resolveResource(segment) {
     const model = pathToModel(segment);
     return crudResources.includes(model) ? model : segment;
@@ -3289,7 +3946,32 @@ function createCmsApiHandler(config) {
         if (method === "GET") return smsMessageTemplateHandlers.GET(req);
         if (method === "PUT") return smsMessageTemplateHandlers.PUT(req);
       }
+      {
+        const kbMatch = matchLlmAgentKnowledgeRoute(path);
+        if (kbMatch) {
+          if (!llmAgentKnowledgeHandlers) {
+            return config.json(
+              {
+                error: "LLM agent knowledge is not available",
+                hint: "With chat enabled, routes usually work automatically. Otherwise pass llmAgentKnowledge. If this persists, ensure entityMap includes knowledge_base_documents, knowledge_base_chunks, llm_agent_knowledge_documents, and run migrations."
+              },
+              { status: 503 }
+            );
+          }
+          const { slug, documentId } = kbMatch;
+          if (method === "DELETE" && documentId != null && documentId !== "") {
+            return llmAgentKnowledgeHandlers.unlink(req, slug, documentId);
+          }
+          if (method === "GET" && (documentId == null || documentId === "")) {
+            return llmAgentKnowledgeHandlers.list(req, slug);
+          }
+          if (method === "POST" && (documentId == null || documentId === "")) {
+            return llmAgentKnowledgeHandlers.post(req, slug);
+          }
+        }
+      }
       if (path[0] === "chat" && chatHandlers) {
+        if (path.length === 2 && path[1] === "config" && method === "GET") return chatHandlers.publicConfig(req);
         if (path.length === 2 && path[1] === "identify" && method === "POST") return chatHandlers.identify(req);
         if (path.length === 4 && path[1] === "conversations" && path[3] === "messages" && method === "GET") return chatHandlers.getMessages(req, path[2]);
         if (path.length === 2 && path[1] === "messages" && method === "POST") return chatHandlers.postMessage(req);
@@ -3358,7 +4040,7 @@ function createCmsApiHandler(config) {
 }
 
 // src/api/storefront-handlers.ts
-import { In as In2, IsNull as IsNull4 } from "typeorm";
+import { In as In3, IsNull as IsNull4 } from "typeorm";
 
 // src/lib/is-valid-signup-email.ts
 var MAX_EMAIL = 254;
@@ -4962,7 +5644,7 @@ function createStorefrontApiHandler(config) {
           const previewByOrder = {};
           if (orderIds.length) {
             const oItems = await orderItemRepo().find({
-              where: { orderId: In2(orderIds) },
+              where: { orderId: In3(orderIds) },
               relations: ["product"],
               order: { id: "ASC" }
             });
@@ -5098,6 +5780,7 @@ export {
   createForgotPasswordHandler,
   createFormBySlugHandler,
   createInviteAcceptHandler,
+  createLlmAgentKnowledgeHandlers,
   createMediaZipExtractHandler,
   createSetPasswordHandler,
   createSettingsApiHandlers,
@@ -5107,6 +5790,10 @@ export {
   createUserAvatarHandler,
   createUserProfileHandler,
   createUsersApiHandlers,
-  getPublicSettingsGroup
+  getPublicSettingsGroup,
+  mergeGuardrailsIntoSystemPrompt,
+  parseLlmAgentValidationRules,
+  validateUserMessageAgainstAgentRules,
+  validateUserMessageAgainstStructuredRules
 };
 //# sourceMappingURL=api.js.map