@elizaos/agent 0.25.8 → 2.0.0-alpha.83

package/packages/agent/src/api/knowledge-routes.js

@@ -0,0 +1,931 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as requestHttp, } from "node:http";
+import { request as requestHttps } from "node:https";
+import net from "node:net";
+import { Readable } from "node:stream";
+import { isBlockedPrivateOrLinkLocalIp, normalizeHostLike, } from "../security/network-policy";
+import { parseClampedFloat, parsePositiveInteger, } from "../utils/number-parsing";
+import { getKnowledgeService, } from "./knowledge-service-loader";
+const FRAGMENT_COUNT_BATCH_SIZE = 500;
+const KNOWLEDGE_UPLOAD_MAX_BODY_BYTES = 32 * 1_048_576; // 32 MB
+const MAX_BULK_DOCUMENTS = 100;
+const MAX_URL_IMPORT_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_YOUTUBE_WATCH_PAGE_BYTES = 2 * 1024 * 1024; // 2 MB
+const MAX_YOUTUBE_TRANSCRIPT_BYTES = 10 * 1024 * 1024; // 10 MB
+const URL_FETCH_TIMEOUT_MS = 15_000;
+const BLOCKED_HOST_LITERALS = new Set([
+    "localhost",
+    "metadata.google.internal",
+]);
+function toSafeNumber(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+function hasUuidId(memory) {
+    return typeof memory.id === "string" && memory.id.length > 0;
+}
+function hasUuidIdAndCreatedAt(memory) {
+    return hasUuidId(memory) && typeof memory.createdAt === "number";
+}
+async function countKnowledgeFragmentsForDocument(knowledgeService, roomId, documentId) {
+    let offset = 0;
+    let fragmentCount = 0;
+    while (true) {
+        const knowledgeBatch = await knowledgeService.getMemories({
+            tableName: "knowledge",
+            roomId,
+            count: FRAGMENT_COUNT_BATCH_SIZE,
+            offset,
+        });
+        if (knowledgeBatch.length === 0) {
+            break;
+        }
+        fragmentCount += knowledgeBatch.filter((memory) => {
+            const metadata = memory.metadata;
+            return metadata?.documentId === documentId;
+        }).length;
+        if (knowledgeBatch.length < FRAGMENT_COUNT_BATCH_SIZE) {
+            break;
+        }
+        offset += FRAGMENT_COUNT_BATCH_SIZE;
+    }
+    return fragmentCount;
+}
+async function mapKnowledgeFragmentsByDocumentId(knowledgeService, roomId, documentIds) {
+    const fragmentCounts = new Map();
+    const trackedDocumentIds = new Set(documentIds);
+    for (const documentId of trackedDocumentIds) {
+        fragmentCounts.set(documentId, 0);
+    }
+    if (trackedDocumentIds.size === 0)
+        return fragmentCounts;
+    let offset = 0;
+    while (true) {
+        const knowledgeBatch = await knowledgeService.getMemories({
+            tableName: "knowledge",
+            roomId,
+            count: FRAGMENT_COUNT_BATCH_SIZE,
+            offset,
+        });
+        if (knowledgeBatch.length === 0) {
+            break;
+        }
+        for (const memory of knowledgeBatch) {
+            const metadata = memory.metadata;
+            const documentId = metadata?.documentId;
+            if (typeof documentId === "string" &&
+                trackedDocumentIds.has(documentId)) {
+                const currentCount = fragmentCounts.get(documentId) ?? 0;
+                fragmentCounts.set(documentId, currentCount + 1);
+            }
+        }
+        if (knowledgeBatch.length < FRAGMENT_COUNT_BATCH_SIZE) {
+            break;
+        }
+        offset += FRAGMENT_COUNT_BATCH_SIZE;
+    }
+    return fragmentCounts;
+}
+async function listKnowledgeFragmentsForDocument(knowledgeService, roomId, documentId) {
+    let offset = 0;
+    const fragmentIds = [];
+    while (true) {
+        const knowledgeBatch = await knowledgeService.getMemories({
+            tableName: "knowledge",
+            roomId,
+            count: FRAGMENT_COUNT_BATCH_SIZE,
+            offset,
+        });
+        for (const memory of knowledgeBatch) {
+            const metadata = memory.metadata;
+            if (metadata?.documentId === documentId && hasUuidId(memory)) {
+                fragmentIds.push(memory.id);
+            }
+        }
+        if (knowledgeBatch.length < FRAGMENT_COUNT_BATCH_SIZE) {
+            break;
+        }
+        offset += FRAGMENT_COUNT_BATCH_SIZE;
+    }
+    return fragmentIds;
+}
+function isBlockedIp(ip) {
+    return isBlockedPrivateOrLinkLocalIp(ip);
+}
+function toRequestHeaders(headers) {
+    const normalized = {};
+    headers.forEach((value, key) => {
+        normalized[key] = value;
+    });
+    return normalized;
+}
+function responseFromIncomingMessage(response) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(response.headers)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else if (typeof value === "string") {
+            headers.set(key, value);
+        }
+    }
+    const status = response.statusCode ?? 500;
+    const body = status === 204 || status === 205 || status === 304
+        ? null
+        : Readable.toWeb(response);
+    return new Response(body, {
+        status,
+        statusText: response.statusMessage,
+        headers,
+    });
+}
+async function requestWithPinnedAddress(input) {
+    const { url, init, target, timeoutMs } = input;
+    if (init.body !== undefined && init.body !== null) {
+        throw new Error("URL fetch request body is not supported");
+    }
+    const method = (init.method ?? "GET").toUpperCase();
+    const headers = toRequestHeaders(new Headers(init.headers));
+    const requestFn = url.protocol === "https:" ? requestHttps : requestHttp;
+    const family = net.isIP(target.pinnedAddress) === 6 ? 6 : 4;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const signal = init.signal;
+        let timeoutHandle = null;
+        const settle = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle !== null)
+                clearTimeout(timeoutHandle);
+            signal?.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => {
+            request.destroy(new DOMException("Aborted", "AbortError"));
+        };
+        const requestOptions = {
+            protocol: url.protocol,
+            hostname: target.hostname,
+            port: url.port ? Number(url.port) : undefined,
+            method,
+            path: `${url.pathname}${url.search}`,
+            headers,
+            lookup: (_hostname, _options, callback) => {
+                callback(null, target.pinnedAddress, family);
+            },
+            ...(url.protocol === "https:"
+                ? { servername: target.hostname }
+                : undefined),
+        };
+        const request = requestFn(requestOptions, (response) => {
+            settle(() => resolve(responseFromIncomingMessage(response)));
+        });
+        request.on("error", (error) => {
+            settle(() => reject(error));
+        });
+        if (signal) {
+            if (signal.aborted) {
+                onAbort();
+            }
+            else {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+        timeoutHandle = setTimeout(() => {
+            request.destroy(new Error(`URL fetch timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        request.end();
+    });
+}
+let pinnedFetchImpl = requestWithPinnedAddress;
+// Test hook for deterministic network simulation without sockets.
+export function __setPinnedFetchImplForTests(impl) {
+    pinnedFetchImpl = impl ?? requestWithPinnedAddress;
+}
+async function resolveSafeUrlTarget(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { rejection: "Invalid URL format", target: null };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return {
+            rejection: "Only http:// and https:// URLs are allowed",
+            target: null,
+        };
+    }
+    const hostname = normalizeHostLike(parsed.hostname);
+    if (!hostname)
+        return { rejection: "URL hostname is required", target: null };
+    if (BLOCKED_HOST_LITERALS.has(hostname)) {
+        return {
+            rejection: `URL host "${hostname}" is blocked for security reasons`,
+            target: null,
+        };
+    }
+    if (net.isIP(hostname)) {
+        if (isBlockedIp(hostname)) {
+            return {
+                rejection: `URL host "${hostname}" is blocked for security reasons`,
+                target: null,
+            };
+        }
+        return {
+            rejection: null,
+            target: {
+                parsed,
+                hostname,
+                pinnedAddress: hostname,
+            },
+        };
+    }
+    let addresses;
+    try {
+        const resolved = await dnsLookup(hostname, { all: true });
+        addresses = Array.isArray(resolved) ? resolved : [resolved];
+    }
+    catch {
+        return {
+            rejection: `Could not resolve URL host "${hostname}"`,
+            target: null,
+        };
+    }
+    if (addresses.length === 0) {
+        return {
+            rejection: `Could not resolve URL host "${hostname}"`,
+            target: null,
+        };
+    }
+    for (const entry of addresses) {
+        if (isBlockedIp(entry.address)) {
+            return {
+                rejection: `URL host "${hostname}" resolves to blocked address ${entry.address}`,
+                target: null,
+            };
+        }
+    }
+    return {
+        rejection: null,
+        target: {
+            parsed,
+            hostname,
+            pinnedAddress: addresses[0]?.address ?? "",
+        },
+    };
+}
+async function fetchWithSafety(url, init, timeoutMs = URL_FETCH_TIMEOUT_MS) {
+    const { rejection, target } = await resolveSafeUrlTarget(url);
+    if (rejection || !target || !target.pinnedAddress) {
+        throw new Error(rejection ?? "URL validation failed");
+    }
+    try {
+        return await pinnedFetchImpl({
+            url: target.parsed,
+            init,
+            target,
+            timeoutMs,
+        });
+    }
+    catch (error) {
+        if (isAbortError(error)) {
+            throw new Error(`URL fetch timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+}
+function isYouTubeUrl(url) {
+    return /^https?:\/\/(www\.)?(youtube\.com|youtu\.be)/.test(url);
+}
+function extractYouTubeVideoId(url) {
+    // Handle youtu.be/VIDEO_ID
+    const shortMatch = url.match(/youtu\.be\/([a-zA-Z0-9_-]{11})/);
+    if (shortMatch)
+        return shortMatch[1];
+    // Handle youtube.com/watch?v=VIDEO_ID
+    const watchMatch = url.match(/[?&]v=([a-zA-Z0-9_-]{11})/);
+    if (watchMatch)
+        return watchMatch[1];
+    // Handle youtube.com/embed/VIDEO_ID
+    const embedMatch = url.match(/\/embed\/([a-zA-Z0-9_-]{11})/);
+    if (embedMatch)
+        return embedMatch[1];
+    // Handle youtube.com/v/VIDEO_ID
+    const vMatch = url.match(/\/v\/([a-zA-Z0-9_-]{11})/);
+    if (vMatch)
+        return vMatch[1];
+    return null;
+}
+async function fetchYouTubeTranscript(videoId) {
+    // Fetch the video page to get transcript data
+    const watchUrl = `https://www.youtube.com/watch?v=${videoId}`;
+    const response = await fetchWithSafety(watchUrl, {
+        headers: {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+            "Accept-Language": "en-US,en;q=0.9",
+        },
+    });
+    if (!response.ok) {
+        return null;
+    }
+    const html = new TextDecoder().decode(await readResponseBodyWithLimit(response, MAX_YOUTUBE_WATCH_PAGE_BYTES));
+    // Extract the captions track URL from the page
+    const captionsMatch = html.match(/"captions":\s*\{[^}]*"playerCaptionsTracklistRenderer":\s*\{[^}]*"captionTracks":\s*\[([^\]]+)\]/);
+    if (!captionsMatch) {
+        // Try alternative pattern for newer YouTube format
+        const altMatch = html.match(/"captionTracks":\s*\[([^\]]+)\]/);
+        if (!altMatch) {
+            return null;
+        }
+    }
+    // Find the base URL for English captions (or first available)
+    const baseUrlMatch = html.match(/"baseUrl":\s*"(https:\/\/www\.youtube\.com\/api\/timedtext[^"]+)"/);
+    if (!baseUrlMatch) {
+        return null;
+    }
+    // Decode the URL (it's JSON-escaped)
+    const captionUrl = baseUrlMatch[1]
+        .replace(/\\u0026/g, "&")
+        .replace(/\\\//g, "/");
+    // Fetch the transcript
+    const transcriptResponse = await fetchWithSafety(captionUrl, {});
+    if (!transcriptResponse.ok) {
+        return null;
+    }
+    const transcriptXml = new TextDecoder().decode(await readResponseBodyWithLimit(transcriptResponse, MAX_YOUTUBE_TRANSCRIPT_BYTES));
+    // Parse the XML transcript
+    const textMatches = transcriptXml.matchAll(/<text[^>]*>([^<]*)<\/text>/g);
+    const segments = [];
+    for (const match of textMatches) {
+        // Decode HTML entities
+        const text = match[1]
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .replace(/&nbsp;/g, " ")
+            .trim();
+        if (text) {
+            segments.push(text);
+        }
+    }
+    if (segments.length === 0) {
+        return null;
+    }
+    return segments.join(" ");
+}
+function readContentLengthHeader(response) {
+    const raw = response.headers.get("content-length");
+    if (!raw)
+        return null;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return null;
+    return parsed;
+}
+function isAbortError(error) {
+    return error instanceof DOMException
+        ? error.name === "AbortError"
+        : error instanceof Error && error.name === "AbortError";
+}
+async function readResponseBodyWithLimit(response, maxBytes) {
+    const declaredLength = readContentLengthHeader(response);
+    if (declaredLength !== null && declaredLength > maxBytes) {
+        throw new Error(`URL content exceeds maximum size of ${maxBytes} bytes`);
+    }
+    if (!response.body) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength > maxBytes) {
+            throw new Error(`URL content exceeds maximum size of ${maxBytes} bytes`);
+        }
+        return bytes;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                throw new Error(`URL content exceeds maximum size of ${maxBytes} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (err) {
+        try {
+            await reader.cancel(err);
+        }
+        catch {
+            // Best effort cleanup; keep the original error.
+        }
+        throw err;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const output = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}
+async function fetchUrlContent(url) {
+    // Check if it's a YouTube URL
+    if (isYouTubeUrl(url)) {
+        const videoId = extractYouTubeVideoId(url);
+        if (!videoId) {
+            throw new Error("Invalid YouTube URL: could not extract video ID");
+        }
+        const transcript = await fetchYouTubeTranscript(videoId);
+        if (!transcript) {
+            throw new Error("Could not fetch YouTube transcript. The video may not have captions available.");
+        }
+        return {
+            content: transcript,
+            contentType: "text/plain",
+            filename: `youtube-${videoId}-transcript.txt`,
+        };
+    }
+    // Regular URL fetch
+    const response = await fetchWithSafety(url, {
+        redirect: "manual",
+        headers: {
+            "User-Agent": "Mozilla/5.0 (compatible; Eliza/1.0; +https://elizaos.ai)",
+        },
+    });
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error("URL redirects are not allowed");
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch URL: ${response.status} ${response.statusText}`);
+    }
+    const contentType = response.headers.get("content-type") || "application/octet-stream";
+    const urlObj = new URL(url);
+    const pathSegments = urlObj.pathname.split("/");
+    const encodedFilename = pathSegments[pathSegments.length - 1] || "document";
+    const filename = decodeURIComponent(encodedFilename);
+    const buffer = await readResponseBodyWithLimit(response, MAX_URL_IMPORT_BYTES);
+    // For binary content, return as base64
+    const isBinary = contentType.startsWith("application/pdf") ||
+        contentType.startsWith("application/msword") ||
+        contentType.startsWith("application/vnd.openxmlformats-officedocument") ||
+        contentType.startsWith("image/");
+    if (isBinary) {
+        const base64 = Buffer.from(buffer).toString("base64");
+        return { content: base64, contentType, filename };
+    }
+    // For text content, return as string
+    const text = new TextDecoder().decode(buffer);
+    return { content: text, contentType, filename };
+}
+export async function handleKnowledgeRoutes(ctx) {
+    const { req, res, method, pathname, url, runtime, json, error, readJsonBody, } = ctx;
+    if (!pathname.startsWith("/api/knowledge"))
+        return false;
+    const { service: knowledgeService, reason } = await getKnowledgeService(runtime);
+    if (!knowledgeService) {
+        if (reason === "timeout") {
+            res.setHeader("Retry-After", "5");
+            error(res, "Knowledge service is still loading. Please retry shortly.", 503);
+        }
+        else {
+            error(res, "Knowledge service is not available. Agent may not be running.", 503);
+        }
+        return true;
+    }
+    if (!runtime?.agentId) {
+        error(res, "Agent runtime is not available", 503);
+        return true;
+    }
+    const agentId = runtime.agentId;
+    // ── GET /api/knowledge/stats ────────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/knowledge/stats") {
+        const documentCount = await knowledgeService.countMemories({
+            tableName: "documents",
+            roomId: agentId,
+            unique: false,
+        });
+        const fragmentCount = await knowledgeService.countMemories({
+            tableName: "knowledge",
+            roomId: agentId,
+            unique: false,
+        });
+        json(res, {
+            documentCount,
+            fragmentCount,
+            agentId,
+        });
+        return true;
+    }
+    // ── GET /api/knowledge/documents ────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/knowledge/documents") {
+        const limit = parsePositiveInteger(url.searchParams.get("limit"), 100);
+        const offset = parsePositiveInteger(url.searchParams.get("offset"), 0);
+        const documents = await knowledgeService.getMemories({
+            tableName: "documents",
+            roomId: agentId,
+            count: limit,
+            offset: offset > 0 ? offset : undefined,
+        });
+        const documentIds = documents.filter(hasUuidId).map((doc) => doc.id);
+        const fragmentCounts = await mapKnowledgeFragmentsByDocumentId(knowledgeService, agentId, documentIds);
+        // Clean up documents for response (remove embeddings, format metadata)
+        const cleanedDocuments = documents.map((doc) => {
+            const metadata = doc.metadata;
+            const documentId = hasUuidId(doc) ? doc.id : null;
+            return {
+                id: doc.id,
+                filename: metadata?.filename || metadata?.title || "Untitled",
+                contentType: metadata?.fileType || metadata?.contentType || "unknown",
+                fileSize: toSafeNumber(metadata?.fileSize, 0),
+                createdAt: toSafeNumber(doc.createdAt, 0),
+                fragmentCount: documentId !== null && fragmentCounts.has(documentId)
+                    ? (fragmentCounts.get(documentId) ?? 0)
+                    : 0,
+                source: metadata?.source || "upload",
+                url: metadata?.url,
+            };
+        });
+        json(res, {
+            documents: cleanedDocuments,
+            total: cleanedDocuments.length,
+            limit,
+            offset: offset > 0 ? offset : 0,
+        });
+        return true;
+    }
+    // ── GET /api/knowledge/documents/:id ────────────────────────────────────
+    const docIdMatch = /^\/api\/knowledge\/documents\/([^/]+)$/.exec(pathname);
+    if (method === "GET" && docIdMatch) {
+        const documentId = decodeURIComponent(docIdMatch[1]);
+        const documents = await knowledgeService.getMemories({
+            tableName: "documents",
+            roomId: agentId,
+            count: 10000,
+        });
+        const document = documents.find((d) => d.id === documentId);
+        if (!document) {
+            error(res, "Document not found", 404);
+            return true;
+        }
+        // Get fragment count for this document
+        const fragmentCount = await countKnowledgeFragmentsForDocument(knowledgeService, agentId, documentId);
+        const metadata = document.metadata;
+        json(res, {
+            document: {
+                id: document.id,
+                filename: metadata?.filename || metadata?.title || "Untitled",
+                contentType: metadata?.fileType || metadata?.contentType || "unknown",
+                fileSize: toSafeNumber(metadata?.fileSize, 0),
+                createdAt: toSafeNumber(document.createdAt, 0),
+                fragmentCount,
+                source: metadata?.source || "upload",
+                url: metadata?.url,
+                content: document.content,
+            },
+        });
+        return true;
+    }
+    // ── DELETE /api/knowledge/documents/:id ─────────────────────────────────
+    if (method === "DELETE" && docIdMatch) {
+        const documentId = decodeURIComponent(docIdMatch[1]);
+        const fragmentIds = await listKnowledgeFragmentsForDocument(knowledgeService, agentId, documentId);
+        for (const fragmentId of fragmentIds) {
+            await knowledgeService.deleteMemory(fragmentId);
+        }
+        // Then delete the document itself
+        await knowledgeService.deleteMemory(documentId);
+        json(res, {
+            ok: true,
+            deletedFragments: fragmentIds.length,
+        });
+        return true;
+    }
+    async function addKnowledgeDocument(service, document) {
+        let content = document.content;
+        let contentType = document.contentType || "text/plain";
+        const warnings = [];
+        // Image files: the content is base64-encoded binary which can't be
+        // text-extracted. Convert to a text description for embedding.
+        if (contentType.startsWith("image/")) {
+            const includeDescriptions = document.metadata
+                ?.includeImageDescriptions === true;
+            if (includeDescriptions && runtime) {
+                // Try to describe the image via the runtime's vision model
+                try {
+                    const { ModelType } = await import("@elizaos/core");
+                    const dataUri = `data:${contentType};base64,${content}`;
+                    const description = await runtime.useModel(ModelType.IMAGE_DESCRIPTION, {
+                        imageUrl: dataUri,
+                        prompt: `Describe this image in detail for a knowledge base. Focus on text content, data, charts, and key visual elements. Image filename: ${document.filename}`,
+                    });
+                    const descText = typeof description === "string"
+                        ? description
+                        : description.description ||
+                            "Image uploaded";
+                    content = `[Image: ${document.filename}]\n\n${descText}`;
+                    contentType = "text/plain";
+                }
+                catch (err) {
+                    // Vision failed — store as a reference entry
+                    content = `[Image: ${document.filename}] — Image uploaded. Vision description unavailable.`;
+                    contentType = "text/plain";
+                    warnings.push(`Vision description failed for ${document.filename}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                // No vision requested — store as a reference entry
+                content = `[Image: ${document.filename}] — Image uploaded without text extraction.`;
+                contentType = "text/plain";
+            }
+        }
+        // MDX files: treat as markdown
+        if (document.filename?.endsWith(".mdx")) {
+            contentType = "text/markdown";
+        }
+        const result = await service.addKnowledge({
+            agentId,
+            worldId: agentId,
+            roomId: agentId,
+            entityId: agentId,
+            clientDocumentId: "", // Will be generated
+            contentType,
+            originalFilename: document.filename,
+            content,
+            metadata: document.metadata,
+        });
+        const warningsValue = result.warnings;
+        if (Array.isArray(warningsValue)) {
+            for (const w of warningsValue) {
+                if (typeof w === "string")
+                    warnings.push(w);
+            }
+        }
+        return {
+            documentId: result.clientDocumentId,
+            fragmentCount: result.fragmentCount,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    // ── POST /api/knowledge/documents ───────────────────────────────────────
+    // Upload document from base64 content or text
+    if (method === "POST" && pathname === "/api/knowledge/documents") {
+        const body = await readJsonBody(req, res, {
+            maxBytes: KNOWLEDGE_UPLOAD_MAX_BODY_BYTES,
+        });
+        if (!body)
+            return true;
+        if (!body.content || !body.filename) {
+            error(res, "content and filename are required");
+            return true;
+        }
+        const result = await addKnowledgeDocument(knowledgeService, body);
+        json(res, {
+            ok: true,
+            documentId: result.documentId,
+            fragmentCount: result.fragmentCount,
+            warnings: result.warnings,
+        });
+        return true;
+    }
+    // ── POST /api/knowledge/documents/bulk ──────────────────────────────────
+    if (method === "POST" && pathname === "/api/knowledge/documents/bulk") {
+        const body = await readJsonBody(req, res, {
+            maxBytes: KNOWLEDGE_UPLOAD_MAX_BODY_BYTES,
+        });
+        if (!body)
+            return true;
+        if (!Array.isArray(body.documents) || body.documents.length === 0) {
+            error(res, "documents array is required");
+            return true;
+        }
+        if (body.documents.length > MAX_BULK_DOCUMENTS) {
+            error(res, `documents array exceeds limit (${MAX_BULK_DOCUMENTS} per request)`);
+            return true;
+        }
+        const results = [];
+        for (const [index, document] of body.documents.entries()) {
+            const filename = document?.filename || `document-${index + 1}`;
+            if (typeof document?.content !== "string" ||
+                typeof document?.filename !== "string" ||
+                document.content.trim().length === 0 ||
+                document.filename.trim().length === 0) {
+                results.push({
+                    index,
+                    ok: false,
+                    filename,
+                    error: "content and filename must be non-empty strings",
+                });
+                continue;
+            }
+            const normalizedDocument = {
+                ...document,
+                content: document.content,
+                filename: document.filename.trim(),
+            };
+            try {
+                const uploadResult = await addKnowledgeDocument(knowledgeService, normalizedDocument);
+                results.push({
+                    index,
+                    ok: true,
+                    filename,
+                    documentId: uploadResult.documentId,
+                    fragmentCount: uploadResult.fragmentCount,
+                    warnings: uploadResult.warnings,
+                });
+            }
+            catch (err) {
+                results.push({
+                    index,
+                    ok: false,
+                    filename,
+                    error: err instanceof Error ? err.message : "Failed to upload document",
+                });
+            }
+        }
+        const successCount = results.filter((item) => item.ok).length;
+        const failureCount = results.length - successCount;
+        json(res, {
+            ok: failureCount === 0,
+            total: results.length,
+            successCount,
+            failureCount,
+            results,
+        });
+        return true;
+    }
+    // ── POST /api/knowledge/documents/url ───────────────────────────────────
+    // Upload document from URL (including YouTube auto-transcription)
+    if (method === "POST" && pathname === "/api/knowledge/documents/url") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (!body.url?.trim()) {
+            error(res, "url is required");
+            return true;
+        }
+        const urlToFetch = body.url.trim();
+        // Fetch and process the URL content
+        let content;
+        let contentType;
+        let filename;
+        try {
+            ({ content, contentType, filename } = await fetchUrlContent(urlToFetch));
+        }
+        catch (err) {
+            error(res, err instanceof Error ? err.message : "Failed to fetch URL content");
+            return true;
+        }
+        const result = await knowledgeService.addKnowledge({
+            agentId,
+            worldId: agentId,
+            roomId: agentId,
+            entityId: agentId,
+            clientDocumentId: "",
+            contentType,
+            originalFilename: filename,
+            content,
+            metadata: {
+                ...body.metadata,
+                url: urlToFetch,
+                source: isYouTubeUrl(urlToFetch) ? "youtube" : "url",
+            },
+        });
+        json(res, {
+            ok: true,
+            documentId: result.clientDocumentId,
+            fragmentCount: result.fragmentCount,
+            filename,
+            contentType,
+            isYouTubeTranscript: isYouTubeUrl(urlToFetch),
+        });
+        return true;
+    }
+    // ── GET /api/knowledge/search ───────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/knowledge/search") {
+        const query = url.searchParams.get("q");
+        if (!query?.trim()) {
+            error(res, "Search query (q) is required");
+            return true;
+        }
+        const threshold = parseClampedFloat(url.searchParams.get("threshold"), {
+            fallback: 0.3,
+            min: 0,
+            max: 1,
+        });
+        const limit = parsePositiveInteger(url.searchParams.get("limit"), 20);
+        // Create a mock message for the search
+        const searchMessage = {
+            id: crypto.randomUUID(),
+            entityId: agentId,
+            agentId,
+            roomId: agentId,
+            content: { text: query.trim() },
+            createdAt: Date.now(),
+        };
+        const results = await knowledgeService.getKnowledge(searchMessage, {
+            roomId: agentId,
+        });
+        // Filter by threshold and limit
+        const filteredResults = results
+            .filter((r) => (r.similarity ?? 0) >= threshold)
+            .slice(0, limit)
+            .map((r) => {
+            const meta = r.metadata;
+            return {
+                id: r.id,
+                text: r.content?.text || "",
+                similarity: r.similarity,
+                documentId: meta?.documentId,
+                documentTitle: meta?.filename || meta?.title || "",
+                position: meta?.position,
+            };
+        });
+        json(res, {
+            query: query.trim(),
+            threshold,
+            results: filteredResults,
+            count: filteredResults.length,
+        });
+        return true;
+    }
+    // ── GET /api/knowledge/fragments/:documentId ────────────────────────────
+    const fragmentsMatch = /^\/api\/knowledge\/fragments\/([^/]+)$/.exec(pathname);
+    if (method === "GET" && fragmentsMatch) {
+        const documentId = decodeURIComponent(fragmentsMatch[1]);
+        const allFragments = [];
+        let fragmentOffset = 0;
+        while (true) {
+            const fragmentBatch = await knowledgeService.getMemories({
+                tableName: "knowledge",
+                roomId: agentId,
+                count: FRAGMENT_COUNT_BATCH_SIZE,
+                offset: fragmentOffset,
+            });
+            if (fragmentBatch.length === 0) {
+                break;
+            }
+            const matchingFragments = fragmentBatch.filter((fragment) => {
+                const metadata = fragment.metadata;
+                return metadata?.documentId === documentId;
+            });
+            for (const fragment of matchingFragments) {
+                if (!hasUuidIdAndCreatedAt(fragment)) {
+                    continue;
+                }
+                const meta = fragment.metadata;
+                allFragments.push({
+                    id: fragment.id,
+                    text: fragment.content?.text || "",
+                    position: meta?.position,
+                    createdAt: fragment.createdAt,
+                });
+            }
+            if (fragmentBatch.length < FRAGMENT_COUNT_BATCH_SIZE) {
+                break;
+            }
+            fragmentOffset += FRAGMENT_COUNT_BATCH_SIZE;
+        }
+        const documentFragments = allFragments
+            .sort((a, b) => {
+            const posA = typeof a.position === "number" ? a.position : 0;
+            const posB = typeof b.position === "number" ? b.position : 0;
+            return posA - posB;
+        })
+            .map((f) => {
+            return {
+                id: f.id,
+                text: f.text,
+                position: f.position,
+                createdAt: f.createdAt,
+            };
+        });
+        json(res, {
+            documentId,
+            fragments: documentFragments,
+            count: documentFragments.length,
+        });
+        return true;
+    }
+    // Route not matched within /api/knowledge prefix
+    return false;
+}