@elizaos/agent 0.25.9 → 2.0.0-alpha.84

package/packages/agent/src/api/knowledge-service-loader.d.ts

@@ -0,0 +1,51 @@
+import type { AgentRuntime, Memory, UUID } from "@elizaos/core";
+export interface KnowledgeServiceLike {
+    addKnowledge(options: {
+        agentId?: UUID;
+        worldId: UUID;
+        roomId: UUID;
+        entityId: UUID;
+        clientDocumentId: UUID;
+        contentType: string;
+        originalFilename: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        clientDocumentId: string;
+        storedDocumentMemoryId: UUID;
+        fragmentCount: number;
+    }>;
+    getKnowledge(message: Memory, scope?: {
+        roomId?: UUID;
+        worldId?: UUID;
+        entityId?: UUID;
+    }): Promise<Array<{
+        id: UUID;
+        content: {
+            text?: string;
+        };
+        similarity?: number;
+        metadata?: Record<string, unknown>;
+    }>>;
+    getMemories(params: {
+        tableName: string;
+        roomId?: UUID;
+        count?: number;
+        offset?: number;
+        end?: number;
+    }): Promise<Memory[]>;
+    countMemories(params: {
+        tableName: string;
+        roomId?: UUID;
+        unique?: boolean;
+    }): Promise<number>;
+    deleteMemory(memoryId: UUID): Promise<void>;
+}
+export type KnowledgeLoadFailReason = "timeout" | "runtime_unavailable" | "not_registered";
+export interface KnowledgeServiceResult {
+    service: KnowledgeServiceLike | null;
+    reason?: KnowledgeLoadFailReason;
+}
+export declare function getKnowledgeTimeoutMs(): number;
+export declare function getKnowledgeService(runtime: AgentRuntime | null): Promise<KnowledgeServiceResult>;
+//# sourceMappingURL=knowledge-service-loader.d.ts.map

package/packages/agent/src/api/knowledge-service-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-service-loader.d.ts","sourceRoot":"","sources":["../../../../../src/api/knowledge-service-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM,eAAe,CAAC;AAEzE,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,OAAO,EAAE;QACpB,OAAO,CAAC,EAAE,IAAI,CAAC;QACf,OAAO,EAAE,IAAI,CAAC;QACd,MAAM,EAAE,IAAI,CAAC;QACb,QAAQ,EAAE,IAAI,CAAC;QACf,gBAAgB,EAAE,IAAI,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC;QACV,gBAAgB,EAAE,MAAM,CAAC;QACzB,sBAAsB,EAAE,IAAI,CAAC;QAC7B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,IAAI,CAAC;QAAC,OAAO,CAAC,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,EAAE,IAAI,CAAA;KAAE,GACzD,OAAO,CACR,KAAK,CAAC;QACJ,EAAE,EAAE,IAAI,CAAC;QACT,OAAO,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,CACH,CAAC;IACF,WAAW,CAAC,MAAM,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,IAAI,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtB,aAAa,CAAC,MAAM,EAAE;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,IAAI,CAAC;QACd,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpB,YAAY,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAKD,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,YAAY,GAAG,IAAI,GAC3B,OAAO,CAAC,sBAAsB,CAAC,CAwBjC"}

package/packages/agent/src/api/knowledge-service-loader.js

@@ -0,0 +1,34 @@
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_TIMEOUT_MS = 60_000;
+export function getKnowledgeTimeoutMs() {
+    const envVal = process.env.KNOWLEDGE_SERVICE_TIMEOUT_MS;
+    if (!envVal)
+        return DEFAULT_TIMEOUT_MS;
+    const parsed = Number.parseInt(envVal, 10);
+    if (Number.isNaN(parsed) || parsed <= 0)
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(parsed, MAX_TIMEOUT_MS);
+}
+export async function getKnowledgeService(runtime) {
+    if (!runtime) {
+        return { service: null, reason: "runtime_unavailable" };
+    }
+    let service = runtime.getService("knowledge");
+    if (service)
+        return { service };
+    try {
+        const servicePromise = runtime.getServiceLoadPromise("knowledge");
+        const timeoutMs = getKnowledgeTimeoutMs();
+        const timeout = new Promise((_resolve, reject) => {
+            setTimeout(() => reject(new Error("knowledge service timeout")), timeoutMs);
+        });
+        await Promise.race([servicePromise, timeout]);
+        service = runtime.getService("knowledge");
+        if (service)
+            return { service };
+        return { service: null, reason: "not_registered" };
+    }
+    catch {
+        return { service: null, reason: "timeout" };
+    }
+}

package/packages/agent/src/api/memory-bounds.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure helper functions for bounded in-memory data structures.
+ * Extracted from server.ts so they can be unit-tested in isolation.
+ *
+ * @module
+ */
+interface RateLimitEntry {
+    count: number;
+    resetAt: number;
+}
+/**
+ * Evict expired entries from a rate-limit map when it exceeds `threshold`.
+ * Safe to call during iteration (Map spec permits deletion during for-of).
+ */
+export declare function sweepExpiredEntries(map: Map<string, RateLimitEntry>, now: number, threshold: number): void;
+interface ConversationLike {
+    updatedAt: string;
+}
+/**
+ * Evict the oldest conversation (by `updatedAt`) when the map exceeds `cap`.
+ * Returns the evicted key, or null if no eviction was needed.
+ */
+export declare function evictOldestConversation<T extends ConversationLike>(map: Map<string, T>, cap: number): string | null;
+/**
+ * Push an entry to a bounded buffer and batch-evict when the high-water
+ * mark is reached.  Returns the current buffer length.
+ *
+ * @param buffer   - The array to push into.
+ * @param entry    - The item to append.
+ * @param highWater - Trigger eviction when `buffer.length` exceeds this.
+ * @param evictCount - Number of oldest entries to remove on eviction.
+ */
+export declare function pushWithBatchEvict<T>(buffer: T[], entry: T, highWater: number, evictCount: number): number;
+interface CachedFile {
+    body: Buffer;
+    mtimeMs: number;
+}
+/**
+ * Retrieve a file from a bounded cache, reading from disk on miss.
+ * Files larger than `fileSizeLimit` are never cached.
+ *
+ * @param cache         - The Map serving as the LRU-ish cache.
+ * @param filePath      - Absolute path to the file.
+ * @param mtimeMs       - File's last-modified time (for invalidation).
+ * @param readFile      - Callback that reads the file (injected for testing).
+ * @param maxEntries    - Maximum number of cached files.
+ * @param fileSizeLimit - Maximum file size (bytes) eligible for caching.
+ */
+export declare function getOrReadCachedFile(cache: Map<string, CachedFile>, filePath: string, mtimeMs: number, readFile: (p: string) => Buffer, maxEntries: number, fileSizeLimit: number): Buffer;
+export {};
+//# sourceMappingURL=memory-bounds.d.ts.map

package/packages/agent/src/api/memory-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-bounds.d.ts","sourceRoot":"","sources":["../../../../../src/api/memory-bounds.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,UAAU,cAAc;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,IAAI,CAKN;AAID,UAAU,gBAAgB;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,gBAAgB,EAChE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EACnB,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAcf;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,CAAC,EAAE,EACX,KAAK,EAAE,CAAC,EACR,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAMR;AAID,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC/B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,CAaR"}

package/packages/agent/src/api/memory-bounds.js

@@ -0,0 +1,81 @@
+/**
+ * Pure helper functions for bounded in-memory data structures.
+ * Extracted from server.ts so they can be unit-tested in isolation.
+ *
+ * @module
+ */
+/**
+ * Evict expired entries from a rate-limit map when it exceeds `threshold`.
+ * Safe to call during iteration (Map spec permits deletion during for-of).
+ */
+export function sweepExpiredEntries(map, now, threshold) {
+    if (map.size <= threshold)
+        return;
+    for (const [k, v] of map) {
+        if (now > v.resetAt)
+            map.delete(k);
+    }
+}
+/**
+ * Evict the oldest conversation (by `updatedAt`) when the map exceeds `cap`.
+ * Returns the evicted key, or null if no eviction was needed.
+ */
+export function evictOldestConversation(map, cap) {
+    if (map.size <= cap)
+        return null;
+    let oldestKey = null;
+    let oldestTime = Infinity;
+    for (const [k, v] of map) {
+        const t = new Date(v.updatedAt).getTime();
+        if (t < oldestTime) {
+            oldestTime = t;
+            oldestKey = k;
+        }
+    }
+    if (oldestKey)
+        map.delete(oldestKey);
+    return oldestKey;
+}
+// ── Log buffer batch eviction ─────────────────────────────────────────
+/**
+ * Push an entry to a bounded buffer and batch-evict when the high-water
+ * mark is reached.  Returns the current buffer length.
+ *
+ * @param buffer   - The array to push into.
+ * @param entry    - The item to append.
+ * @param highWater - Trigger eviction when `buffer.length` exceeds this.
+ * @param evictCount - Number of oldest entries to remove on eviction.
+ */
+export function pushWithBatchEvict(buffer, entry, highWater, evictCount) {
+    buffer.push(entry);
+    if (buffer.length > highWater) {
+        buffer.splice(0, evictCount);
+    }
+    return buffer.length;
+}
+/**
+ * Retrieve a file from a bounded cache, reading from disk on miss.
+ * Files larger than `fileSizeLimit` are never cached.
+ *
+ * @param cache         - The Map serving as the LRU-ish cache.
+ * @param filePath      - Absolute path to the file.
+ * @param mtimeMs       - File's last-modified time (for invalidation).
+ * @param readFile      - Callback that reads the file (injected for testing).
+ * @param maxEntries    - Maximum number of cached files.
+ * @param fileSizeLimit - Maximum file size (bytes) eligible for caching.
+ */
+export function getOrReadCachedFile(cache, filePath, mtimeMs, readFile, maxEntries, fileSizeLimit) {
+    const cached = cache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs)
+        return cached.body;
+    const body = readFile(filePath);
+    if (body.length <= fileSizeLimit) {
+        if (cache.size >= maxEntries) {
+            const firstKey = cache.keys().next().value;
+            if (firstKey !== undefined)
+                cache.delete(firstKey);
+        }
+        cache.set(filePath, { body, mtimeMs });
+    }
+    return body;
+}

package/packages/agent/src/api/memory-routes.d.ts

@@ -0,0 +1,9 @@
+import { type AgentRuntime } from "@elizaos/core";
+import type { RouteRequestContext } from "./route-helpers";
+export interface MemoryRouteContext extends RouteRequestContext {
+    url: URL;
+    runtime: AgentRuntime | null;
+    agentName: string;
+}
+export declare function handleMemoryRoutes(ctx: MemoryRouteContext): Promise<boolean>;
+//# sourceMappingURL=memory-routes.d.ts.map

package/packages/agent/src/api/memory-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/memory-routes.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,YAAY,EAOlB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAU3D,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,GAAG,EAAE,GAAG,CAAC;IACT,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAiMD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,OAAO,CAAC,CA+HlB"}

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

@@ -0,0 +1,241 @@
+import crypto from "node:crypto";
+import { ChannelType, createMessageMemory, ModelType, stringToUuid, } from "@elizaos/core";
+import { parsePositiveInteger } from "../utils/number-parsing";
+import { getKnowledgeService } from "./knowledge-service-loader";
+const HASH_MEMORY_SOURCE = "hash_memory";
+const MEMORY_SEARCH_SCAN_LIMIT = 500;
+const MEMORY_SEARCH_DEFAULT_LIMIT = 10;
+const MEMORY_SEARCH_MAX_LIMIT = 50;
+const QUICK_CONTEXT_DEFAULT_LIMIT = 8;
+const QUICK_CONTEXT_MAX_LIMIT = 20;
+const QUICK_CONTEXT_KNOWLEDGE_THRESHOLD = 0.2;
+function resolveAgentName(runtime, fallbackName) {
+    return runtime.character.name?.trim() || fallbackName || "Eliza";
+}
+async function ensureMemoryConnection(runtime, agentName) {
+    const entityId = runtime.agentId;
+    const roomId = stringToUuid(`${agentName}-hash-memory-room`);
+    const worldId = stringToUuid(`${agentName}-hash-memory-world`);
+    const messageServerId = stringToUuid(`${agentName}-hash-memory-server`);
+    await runtime.ensureConnection({
+        entityId,
+        roomId,
+        worldId,
+        userName: "User",
+        source: "client_chat",
+        channelId: `${agentName}-hash-memory`,
+        type: ChannelType.DM,
+        messageServerId,
+        metadata: { ownership: { ownerId: entityId } },
+    });
+    return { roomId, entityId };
+}
+function scoreMemoryText(text, query) {
+    const normalizedText = text.toLowerCase();
+    const normalizedQuery = query.toLowerCase();
+    if (!normalizedText || !normalizedQuery)
+        return 0;
+    const terms = normalizedQuery
+        .split(/\s+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2);
+    const containsWhole = normalizedText.includes(normalizedQuery) ? 1 : 0;
+    if (terms.length === 0) {
+        return containsWhole;
+    }
+    let termMatches = 0;
+    for (const term of terms) {
+        if (normalizedText.includes(term))
+            termMatches += 1;
+    }
+    return containsWhole + termMatches / terms.length;
+}
+async function searchMemoryNotes(runtime, roomId, query, limit) {
+    const memories = await runtime.getMemories({
+        roomId,
+        tableName: "messages",
+        count: MEMORY_SEARCH_SCAN_LIMIT,
+    });
+    const hits = [];
+    for (const memory of memories) {
+        const text = memory.content?.text?.trim();
+        if (!text)
+            continue;
+        const source = memory.content?.source;
+        if (source !== HASH_MEMORY_SOURCE)
+            continue;
+        const score = scoreMemoryText(text, query);
+        if (score <= 0)
+            continue;
+        hits.push({
+            id: memory.id ?? crypto.randomUUID(),
+            text,
+            createdAt: memory.createdAt ?? 0,
+            score,
+        });
+    }
+    hits.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return b.createdAt - a.createdAt;
+    });
+    return hits.slice(0, limit);
+}
+async function searchKnowledge(runtime, query, limit) {
+    const knowledge = await getKnowledgeService(runtime);
+    const knowledgeService = knowledge.service;
+    if (!knowledgeService || !runtime.agentId)
+        return [];
+    const agentId = runtime.agentId;
+    const searchMessage = {
+        id: crypto.randomUUID(),
+        entityId: agentId,
+        agentId,
+        roomId: agentId,
+        content: { text: query },
+        createdAt: Date.now(),
+    };
+    const matches = await knowledgeService.getKnowledge(searchMessage, {
+        roomId: agentId,
+    });
+    return matches
+        .filter((match) => (match.similarity ?? 0) >= QUICK_CONTEXT_KNOWLEDGE_THRESHOLD)
+        .slice(0, limit)
+        .map((match) => {
+        const metadata = match.metadata;
+        return {
+            id: match.id,
+            text: match.content?.text ?? "",
+            similarity: match.similarity ?? 0,
+            documentId: typeof metadata?.documentId === "string"
+                ? metadata.documentId
+                : undefined,
+            documentTitle: typeof metadata?.filename === "string"
+                ? metadata.filename
+                : typeof metadata?.title === "string"
+                    ? metadata.title
+                    : undefined,
+            position: typeof metadata?.position === "number"
+                ? metadata.position
+                : undefined,
+        };
+    });
+}
+function buildQuickContextPrompt(params) {
+    const { query, memories, knowledge } = params;
+    const memorySection = memories.length > 0
+        ? memories
+            .map((item, index) => `- [M${index + 1}] ${item.text}`)
+            .join("\n")
+        : "- none";
+    const knowledgeSection = knowledge.length > 0
+        ? knowledge
+            .map((item, index) => `- [K${index + 1}] ${item.text}`)
+            .join("\n")
+        : "- none";
+    return [
+        "You are a concise context assistant.",
+        "Answer only from the provided context. If context is insufficient, say so explicitly.",
+        "Keep the answer under 120 words.",
+        "",
+        `Query: ${query}`,
+        "",
+        "Saved memory notes:",
+        memorySection,
+        "",
+        "Knowledge snippets:",
+        knowledgeSection,
+    ].join("\n");
+}
+export async function handleMemoryRoutes(ctx) {
+    const { req, res, method, pathname, url, runtime, agentName, json, error, readJsonBody, } = ctx;
+    if (!pathname.startsWith("/api/memory") &&
+        pathname !== "/api/context/quick") {
+        return false;
+    }
+    if (!runtime) {
+        error(res, "Agent runtime is not available", 503);
+        return true;
+    }
+    const resolvedAgentName = resolveAgentName(runtime, agentName);
+    const { roomId, entityId } = await ensureMemoryConnection(runtime, resolvedAgentName);
+    if (method === "POST" && pathname === "/api/memory/remember") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const text = typeof body.text === "string" ? body.text.trim() : "";
+        if (!text) {
+            error(res, "text is required", 400);
+            return true;
+        }
+        const createdAt = Date.now();
+        const message = createMessageMemory({
+            id: crypto.randomUUID(),
+            entityId,
+            roomId,
+            content: {
+                text,
+                source: HASH_MEMORY_SOURCE,
+                channelType: ChannelType.DM,
+            },
+        });
+        await runtime.createMemory(message, "messages");
+        json(res, {
+            ok: true,
+            id: message.id,
+            text,
+            createdAt,
+        });
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/memory/search") {
+        const query = url.searchParams.get("q")?.trim() ?? "";
+        if (!query) {
+            error(res, "Search query (q) is required", 400);
+            return true;
+        }
+        const requestedLimit = parsePositiveInteger(url.searchParams.get("limit"), MEMORY_SEARCH_DEFAULT_LIMIT);
+        const limit = Math.min(Math.max(requestedLimit, 1), MEMORY_SEARCH_MAX_LIMIT);
+        const results = await searchMemoryNotes(runtime, roomId, query, limit);
+        json(res, {
+            query,
+            results,
+            count: results.length,
+            limit,
+        });
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/context/quick") {
+        const query = url.searchParams.get("q")?.trim() ?? "";
+        if (!query) {
+            error(res, "Search query (q) is required", 400);
+            return true;
+        }
+        const requestedLimit = parsePositiveInteger(url.searchParams.get("limit"), QUICK_CONTEXT_DEFAULT_LIMIT);
+        const limit = Math.min(Math.max(requestedLimit, 1), QUICK_CONTEXT_MAX_LIMIT);
+        const [memories, knowledge] = await Promise.all([
+            searchMemoryNotes(runtime, roomId, query, limit),
+            searchKnowledge(runtime, query, limit),
+        ]);
+        const prompt = buildQuickContextPrompt({ query, memories, knowledge });
+        let answer = "I couldn't generate a quick answer right now.";
+        try {
+            const response = await runtime.useModel(ModelType.TEXT_SMALL, { prompt });
+            const text = typeof response === "string" ? response : String(response);
+            if (text.trim()) {
+                answer = text.trim();
+            }
+        }
+        catch {
+            // Keep fallback answer.
+        }
+        json(res, {
+            query,
+            answer,
+            memories,
+            knowledge,
+        });
+        return true;
+    }
+    return false;
+}

package/packages/agent/src/api/merkle-tree.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Merkle tree service for whitelist proof generation.
+ *
+ * Builds a Merkle tree from verified addresses in whitelist.json and
+ * generates proofs that can be submitted to the smart contract's
+ * `mintWhitelist(name, endpoint, capHash, proof[])` function.
+ *
+ * This is the missing bridge between:
+ *   whitelist.json  →  Merkle tree  →  on-chain mintWhitelist()
+ *
+ * The contract stores a `merkleRoot()` and verifies each mint against
+ * a proof derived from the caller's address.
+ *
+ * Standard: leaves = keccak256(abi.encodePacked(address))
+ *           sorted pairs to ensure deterministic tree construction.
+ *
+ * @see drop-service.ts  — mintWithWhitelist() consumer
+ * @see twitter-verify.ts — one source of whitelist addresses
+ * @see nft-verify.ts     — another source of whitelist addresses
+ */
+export interface MerkleProofResult {
+    /** The proof array (bytes32[]) to submit to mintWhitelist(). */
+    proof: string[];
+    /** The leaf hash for this address. */
+    leaf: string;
+    /** The root of the current tree. */
+    root: string;
+    /** Whether this address is in the tree. */
+    isWhitelisted: boolean;
+}
+export interface MerkleTreeInfo {
+    /** The root hash of the current tree. */
+    root: string;
+    /** Total number of addresses in the tree. */
+    addressCount: number;
+    /** All leaf hashes (sorted). */
+    leaves: string[];
+}
+/**
+ * Hash an address into a Merkle leaf.
+ *
+ * Uses `keccak256(abi.encodePacked(address))` — the standard Solidity
+ * pattern for OpenZeppelin MerkleProof verification.
+ */
+export declare function hashLeaf(address: string): string;
+/**
+ * Build a Merkle tree from an array of leaf hashes.
+ *
+ * Returns the tree as a 2D array where:
+ *   tree[0] = leaves (sorted)
+ *   tree[1] = first level of internal nodes
+ *   ...
+ *   tree[tree.length - 1] = [root]
+ *
+ * Leaves are sorted before building to ensure determinism.
+ */
+export declare function buildTree(leaves: string[]): string[][];
+/**
+ * Get the proof (sibling path) for a leaf in the tree.
+ */
+export declare function getProof(tree: string[][], leaf: string): string[];
+/**
+ * Get the root of the tree.
+ */
+export declare function getRoot(tree: string[][]): string;
+/**
+ * Verify a proof against a root.
+ *
+ * Recomputes the root from the leaf + proof path and checks
+ * if it matches the expected root.
+ */
+export declare function verifyProof(leaf: string, proof: string[], expectedRoot: string): boolean;
+/**
+ * Build a Merkle tree from the current whitelist.
+ *
+ * Reads all verified addresses from whitelist.json, hashes them into
+ * leaves, and builds the tree.
+ */
+export declare function buildWhitelistTree(): {
+    tree: string[][];
+    info: MerkleTreeInfo;
+};
+/**
+ * Generate a Merkle proof for a specific address.
+ *
+ * Returns the proof, leaf, root, and whether the address is whitelisted.
+ * The proof can be passed directly to `mintWhitelist()` on the contract.
+ */
+export declare function generateProof(walletAddress: string): MerkleProofResult;
+//# sourceMappingURL=merkle-tree.d.ts.map

package/packages/agent/src/api/merkle-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle-tree.d.ts","sourceRoot":"","sources":["../../../../../src/api/merkle-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAID;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKhD;AAoBD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,EAAE,CA4BtD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAmBjE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EAAE,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAMT;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC;CACtB,CAmBA;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,iBAAiB,CA8BtE"}