@dainprotocol/service-sdk 2.0.91 → 2.0.93

package/dist/service/server.js

@@ -9,15 +9,15 @@ const cors_1 = require("hono/cors");
 const http_exception_1 = require("hono/http-exception");
 const auth_1 = require("./auth");
 const schemaStructure_1 = require("../lib/schemaStructure");
+const toolDiscovery_1 = require("../lib/toolDiscovery");
 const oauth2_1 = require("./oauth2");
 const bs58_1 = tslib_1.__importDefault(require("bs58"));
 const processes_1 = require("./processes");
 const streaming_1 = require("hono/streaming");
 const package_json_1 = tslib_1.__importDefault(require("../../package.json"));
 const zod_1 = require("zod");
-const ed25519_1 = require("@noble/curves/ed25519");
-const sha256_1 = require("@noble/hashes/sha256");
-const utils_1 = require("@noble/hashes/utils");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const sseSignature_1 = require("../lib/sseSignature");
 const auth_2 = require("./auth");
 const core_1 = require("./core");
 const hitl_1 = require("./hitl");
@@ -32,6 +32,46 @@ function debugWarn(...args) {
         console.warn(...args);
     }
 }
+/**
+ * Extract a user-safe error message. If `err` is a ZodError (or `err.message`
+ * looks like a raw Zod v4 issue-array JSON `"[{...}]"`), re-summarize as
+ * `"<path>: <msg>; <path>: <msg>"` so it never lands verbatim in chat text.
+ *
+ * Backstop for the tool-output validation leak: the 2026-04-17 whitelist
+ * regression surfaced `[{"code":"invalid_type","path":["markets"],...}]` in
+ * user-visible chat because the four SSE/non-SSE error exits below all do
+ * `text: \`Error: ${error.message}\``. This helper neutralizes that class
+ * of bug for ANY ZodError thrown anywhere in the tool-exec pipeline, not
+ * just the one we already fixed at the source in core.ts.
+ */
+function sanitizeErrorMessage(err) {
+    if (err instanceof zod_1.z.ZodError) {
+        const summary = err.issues
+            .map((i) => `${i.path.join(".") || "root"}: ${i.message}`)
+            .join("; ");
+        return summary || "Validation failed";
+    }
+    const raw = err?.message;
+    if (typeof raw !== "string" || raw.length === 0)
+        return "Unknown error";
+    const trimmed = raw.trimStart();
+    if (trimmed.startsWith("[{") || trimmed.startsWith("[ {")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                const summary = parsed
+                    .map((i) => `${Array.isArray(i.path) ? i.path.join(".") || "root" : "root"}: ${i.message ?? "invalid"}`)
+                    .join("; ");
+                if (summary)
+                    return summary;
+            }
+        }
+        catch {
+            /* fall through, return raw message */
+        }
+    }
+    return raw;
+}
 function getFirstForwardedValue(value) {
     if (!value)
         return undefined;
@@ -78,23 +118,28 @@ function requireScope(requiredScope) {
 // Helper to sign and stream SSE events
 function signedStreamSSE(c, privateKey, config, handler) {
     return (0, streaming_1.streamSSE)(c, async (stream) => {
+        const requestSignal = c.req.raw?.signal;
+        const isAborted = () => stream.aborted || stream.closed || requestSignal?.aborted === true;
         const signedStream = {
             writeSSE: async (event) => {
+                if (isAborted())
+                    return;
                 const timestamp = Date.now().toString();
-                const message = `${event.data}:${timestamp}`;
-                const messageHash = (0, sha256_1.sha256)(message);
-                const signatureBytes = ed25519_1.ed25519.sign(messageHash, privateKey);
-                const signature = (0, utils_1.bytesToHex)(signatureBytes);
+                const messageHash = (0, sseSignature_1.hashEventMessage)(event.data, timestamp);
+                const signature = (0, utils_js_1.bytesToHex)(sseSignature_1.ed25519.sign(messageHash, privateKey));
                 // Fast path for non-critical events (progress/UI updates)
-                const isCriticalEvent = event.event === 'result' || event.event === 'process-created';
+                const isCriticalEvent = event.event === 'result' ||
+                    event.event === 'process-created' ||
+                    event.event === 'datasource-update';
                 const dataWithSignature = isCriticalEvent
                     ? JSON.stringify({
                         data: JSON.parse(event.data),
                         _signature: { signature, timestamp, agentId: config.identity.agentId, orgId: config.identity.orgId, address: config.identity.publicKey }
                     })
                     : `{"data":${event.data},"_signature":{"signature":"${signature}","timestamp":"${timestamp}","agentId":"${config.identity.agentId}","orgId":"${config.identity.orgId}","address":"${config.identity.publicKey}"}}`;
-                return stream.writeSSE({ event: event.event, data: dataWithSignature, id: event.id });
-            }
+                await stream.writeSSE({ event: event.event, data: dataWithSignature, id: event.id });
+            },
+            isAborted,
         };
         await handler(signedStream);
     });
@@ -174,11 +219,7 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
         const isHITLPath = hitlPath && c.req.path === hitlPath;
         if (c.req.path.startsWith("/oauth2/callback/") ||
             c.req.path.startsWith("/addons") ||
-            c.req.path.startsWith("/getAllToolsAsJsonSchema") ||
-            c.req.path.startsWith("/getSkills") ||
-            c.req.path.startsWith("/getWebhookTriggers") ||
             c.req.path.startsWith("/metadata") ||
-            c.req.path.startsWith("/recommendations") ||
             c.req.path.startsWith("/ping") ||
             isWebhookPath ||
             isHITLPath) {
@@ -300,15 +341,73 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
         debugLog("[getAgentInfo] API Key - Returning agent info:", agentInfo);
         return agentInfo;
     }
+    async function resolveHealthStatus() {
+        if (!config.healthCheck)
+            return true;
+        try {
+            return await config.healthCheck();
+        }
+        catch {
+            return false;
+        }
+    }
     // Setup default ping route
-    app.get("/ping", (c) => c.json({ message: "pong", platform: "DAIN", service_version: metadata.version, dain_sdk_version: package_json_1.default.version }));
+    app.get("/ping", async (c) => {
+        const healthy = await resolveHealthStatus();
+        return c.json({
+            message: healthy ? "pong" : "unhealthy",
+            platform: "DAIN",
+            service_version: metadata.version,
+            dain_sdk_version: package_json_1.default.version,
+        }, healthy ? 200 : 503);
+    });
     // Metadata endpoint - includes computed supportsUserActions from tools
     app.get("/metadata", (c) => {
         // Compute service-level capability: does ANY tool support user actions (HITL)?
         const supportsUserActions = tools.some((tool) => tool.supportsUserActions === true);
+        const requestedContract = c.req.header("x-butterfly-contract") || c.req.header("X-Butterfly-Contract");
+        const sdkMajor = Number.parseInt(String(package_json_1.default.version).split(".")[0] || "0", 10);
+        const contractVersion = Number.isFinite(sdkMajor) && sdkMajor > 0 ? `${sdkMajor}.0.0` : "0.0.0";
+        const capabilities = {
+            tools: true,
+            contexts: true,
+            widgets: true,
+            datasources: true,
+            streamingTools: true,
+            streamingDatasources: true,
+            datasourcePolicy: true,
+            widgetPolicy: true,
+            toolSafety: true,
+        };
+        const compatibility = (() => {
+            if (!requestedContract)
+                return undefined;
+            const requestedMajor = Number.parseInt(String(requestedContract).split(".")[0] || "0", 10);
+            if (!Number.isFinite(requestedMajor) || requestedMajor <= 0) {
+                return {
+                    requested: requestedContract,
+                    contractVersion,
+                    ok: false,
+                    reason: "Invalid requested contract version",
+                };
+            }
+            const ok = requestedMajor === sdkMajor;
+            return ok
+                ? { requested: requestedContract, contractVersion, ok: true }
+                : {
+                    requested: requestedContract,
+                    contractVersion,
+                    ok: false,
+                    reason: `Requested major ${requestedMajor} does not match service major ${sdkMajor}`,
+                };
+        })();
         return c.json({
             ...metadata,
             supportsUserActions,
+            dainSdkVersion: package_json_1.default.version,
+            contractVersion,
+            capabilities,
+            ...(compatibility ? { compatibility } : {}),
         });
     });
     // Tools list endpoint
@@ -327,6 +426,10 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                 outputSchema,
                 interface: tool.interface,
                 suggestConfirmation: tool.suggestConfirmation,
+                sideEffectClass: tool.sideEffectClass,
+                supportsParallel: tool.supportsParallel,
+                idempotencyScope: tool.idempotencyScope,
+                maxConcurrencyHint: tool.maxConcurrencyHint,
                 supportsUserActions: tool.supportsUserActions,
             };
         });
@@ -427,14 +530,26 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                 oauth2Client,
                 app
             });
-            return {
+            const response = {
                 id: widget.id,
                 name: widget.name,
                 description: widget.description,
                 icon: widget.icon,
                 size: widget.size || "sm",
+                refreshIntervalMs: widget.refreshIntervalMs,
                 ...widgetData
             };
+            if (!("freshness" in response)) {
+                response.freshness = {
+                    freshAt: Date.now(),
+                    transport: "poll",
+                    requestedPolicy: {
+                        refreshIntervalMs: widget.refreshIntervalMs,
+                    },
+                    scope: "account",
+                };
+            }
+            return response;
         }));
         const validWidgets = widgetsFull.filter(w => w !== null);
         const processedResponse = await processPluginsForResponse(validWidgets, body, { extraData: { plugins: processedPluginData.plugins } });
@@ -475,8 +590,19 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
             description: widget.description,
             icon: widget.icon,
             size: widget.size || "sm",
+            refreshIntervalMs: widget.refreshIntervalMs,
             ...widgetData
         };
+        if (!("freshness" in response)) {
+            response.freshness = {
+                freshAt: Date.now(),
+                transport: "poll",
+                requestedPolicy: {
+                    refreshIntervalMs: widget.refreshIntervalMs,
+                },
+                scope: "account",
+            };
+        }
         const processedResponse = await processPluginsForResponse(response, body, { extraData: { plugins: processedPluginData.plugins } });
         return c.json(processedResponse);
     });
@@ -506,6 +632,12 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
             name: datasource.name,
             description: datasource.description,
             type: datasource.type,
+            refreshIntervalMs: datasource.refreshIntervalMs,
+            maxStalenessMs: datasource.maxStalenessMs,
+            transport: datasource.transport,
+            priority: datasource.priority,
+            scope: datasource.scope,
+            dataClass: datasource.dataClass,
             inputSchema: (0, schemaStructure_1.getDetailedSchemaStructure)(datasource.input),
         };
     }
@@ -543,12 +675,32 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                 plugins: pluginsData,
                 oauth2Client
             });
+            const requestedPolicy = {
+                refreshIntervalMs: datasource.refreshIntervalMs,
+                maxStalenessMs: datasource.maxStalenessMs,
+                transport: datasource.transport,
+                priority: datasource.priority,
+                scope: datasource.scope,
+                dataClass: datasource.dataClass,
+            };
             const response = {
                 id: datasource.id,
                 name: datasource.name,
                 description: datasource.description,
                 type: datasource.type,
+                refreshIntervalMs: datasource.refreshIntervalMs,
+                maxStalenessMs: datasource.maxStalenessMs,
+                transport: datasource.transport,
+                priority: datasource.priority,
+                scope: datasource.scope,
+                dataClass: datasource.dataClass,
                 data,
+                freshness: {
+                    freshAt: Date.now(),
+                    transport: datasource.transport || "poll",
+                    requestedPolicy,
+                    scope: datasource.scope,
+                },
             };
             const processedResponse = await processPluginsForResponse(response, { plugins: pluginsData }, { extraData: { plugins: pluginsData } });
             return c.json(processedResponse);
@@ -566,6 +718,149 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
             throw error;
         }
     });
+    // Stream datasource updates over SSE. This is primarily used for "fresh" UIs
+    // (positions/orders) where clients want stream-first updates with a poll fallback.
+    //
+    // Note: This does not require services to implement a separate streaming backend.
+    // The server re-runs the datasource handler on an interval and streams results.
+    app.post("/datasources/:datasourceId/stream", async (c) => {
+        const datasource = datasources.find((ds) => ds.id === c.req.param("datasourceId"));
+        if (!datasource) {
+            throw new http_exception_1.HTTPException(404, { message: "Datasource not found" });
+        }
+        const agentInfo = await getAgentInfo(c);
+        const rawBody = await safeParseBody(c);
+        const hasWrappedParams = rawBody &&
+            typeof rawBody === "object" &&
+            !Array.isArray(rawBody) &&
+            "params" in rawBody;
+        const requestedIntervalMsRaw = hasWrappedParams ? rawBody.intervalMs : undefined;
+        const requestParamsRaw = hasWrappedParams ? rawBody.params : rawBody;
+        let params = await processPluginsForRequest(requestParamsRaw && typeof requestParamsRaw === "object" ? requestParamsRaw : {}, agentInfo);
+        const pluginsData = (params.plugins && typeof params.plugins === "object"
+            ? params.plugins
+            : {});
+        delete params.plugins;
+        let parsedParams;
+        try {
+            parsedParams = datasource.input.parse(params);
+        }
+        catch (error) {
+            if (error instanceof zod_1.z.ZodError) {
+                const missingParams = error.issues
+                    .map((issue) => issue.path.join("."))
+                    .join(", ");
+                return c.json({
+                    error: `Missing or invalid parameters: ${missingParams}`,
+                    code: "INVALID_PARAMS"
+                }, 400);
+            }
+            throw error;
+        }
+        const pluginRequestContext = hasWrappedParams
+            ? {
+                params: parsedParams,
+                intervalMs: requestedIntervalMsRaw,
+                plugins: pluginsData,
+            }
+            : {
+                ...(typeof parsedParams === "object" && parsedParams !== null
+                    ? parsedParams
+                    : {}),
+                plugins: pluginsData,
+            };
+        const oauth2Client = app.oauth2?.getClient();
+        const requestedPolicy = {
+            refreshIntervalMs: datasource.refreshIntervalMs,
+            maxStalenessMs: datasource.maxStalenessMs,
+            transport: datasource.transport,
+            priority: datasource.priority,
+            scope: datasource.scope,
+            dataClass: datasource.dataClass,
+        };
+        const requestedIntervalMs = typeof requestedIntervalMsRaw === "number" && Number.isFinite(requestedIntervalMsRaw) && requestedIntervalMsRaw > 0
+            ? requestedIntervalMsRaw
+            : null;
+        const baseIntervalMs = requestedIntervalMs ??
+            (typeof datasource.refreshIntervalMs === "number" && datasource.refreshIntervalMs > 0
+                ? datasource.refreshIntervalMs
+                : 15_000);
+        const intervalMs = Math.max(1_000, Math.floor(baseIntervalMs));
+        const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+        debugLog(`[SSE] Datasource ${datasource.id} stream start (${intervalMs}ms interval)`);
+        return signedStreamSSE(c, privateKey, config, async (stream) => {
+            let eventId = 0;
+            const emitUpdate = async () => {
+                const data = await datasource.getDatasource(agentInfo, parsedParams, {
+                    plugins: pluginsData,
+                    oauth2Client,
+                });
+                const response = {
+                    id: datasource.id,
+                    name: datasource.name,
+                    description: datasource.description,
+                    type: datasource.type,
+                    refreshIntervalMs: datasource.refreshIntervalMs,
+                    maxStalenessMs: datasource.maxStalenessMs,
+                    transport: datasource.transport,
+                    priority: datasource.priority,
+                    scope: datasource.scope,
+                    dataClass: datasource.dataClass,
+                    data,
+                    freshness: {
+                        freshAt: Date.now(),
+                        transport: "stream",
+                        requestedPolicy,
+                        scope: datasource.scope,
+                    },
+                };
+                const processedResponse = await processPluginsForResponse(response, pluginRequestContext, { extraData: { plugins: pluginsData } });
+                await stream.writeSSE({
+                    event: "datasource-update",
+                    data: JSON.stringify(processedResponse),
+                    id: String(eventId++),
+                });
+            };
+            // Send initial snapshot immediately.
+            try {
+                await emitUpdate();
+            }
+            catch (error) {
+                console.error(`[SSE] Datasource ${datasource.id} initial update failed:`, error);
+                if (!stream.isAborted()) {
+                    await stream.writeSSE({
+                        event: "error",
+                        data: JSON.stringify({ message: error?.message || "Datasource stream error" }),
+                    });
+                }
+                return;
+            }
+            // Continue sending updates until client disconnects.
+            // Hono exposes the underlying Request via c.req.raw, which includes an AbortSignal.
+            const signal = c.req.raw?.signal;
+            while (!stream.isAborted() && !signal?.aborted) {
+                await sleep(intervalMs);
+                if (stream.isAborted() || signal?.aborted)
+                    break;
+                try {
+                    await emitUpdate();
+                }
+                catch (error) {
+                    if (stream.isAborted() || signal?.aborted)
+                        break;
+                    console.error(`[SSE] Datasource ${datasource.id} update failed:`, error);
+                    // Keep the stream alive; clients should rely on poll fallback if needed.
+                    if (!stream.isAborted()) {
+                        await stream.writeSSE({
+                            event: "error",
+                            data: JSON.stringify({ message: error?.message || "Datasource stream error" }),
+                        });
+                    }
+                }
+            }
+            debugLog(`[SSE] Datasource ${datasource.id} stream end`);
+        });
+    });
     function mapAgentInfo(agent) {
         return {
             id: agent.id,
@@ -642,13 +937,23 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
             outputSchema,
             interface: tool.interface,
             suggestConfirmation: tool.suggestConfirmation,
+            sideEffectClass: tool.sideEffectClass,
+            supportsParallel: tool.supportsParallel,
+            idempotencyScope: tool.idempotencyScope,
+            maxConcurrencyHint: tool.maxConcurrencyHint,
             supportsUserActions: tool.supportsUserActions,
         };
     }
     app.get("/getAllToolsAsJsonSchema", (c) => {
+        const toolInfo = tools.map(mapToolToJsonSchema);
+        const reccomendedPrompts = toolboxes.map((toolbox) => toolbox.recommendedPrompt);
         return c.json({
-            tools: tools.map(mapToolToJsonSchema),
-            reccomendedPrompts: toolboxes.map((toolbox) => toolbox.recommendedPrompt),
+            tools: toolInfo,
+            reccomendedPrompts,
+            schemaVersion: (0, toolDiscovery_1.computeToolDiscoverySchemaVersion)({
+                tools: toolInfo,
+                reccomendedPrompts,
+            }),
         });
     });
     app.post("/getAllToolsAsJsonSchema", async (c) => {
@@ -657,9 +962,14 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
         const processedPluginData = await processPluginsForRequest(body, agentInfo);
         const toolInfo = tools.map(mapToolToJsonSchema);
         debugLog(`[getAllToolsAsJsonSchema POST] Returning ${toolInfo.length} tools`);
+        const reccomendedPrompts = toolboxes.map((toolbox) => toolbox.recommendedPrompt);
         const response = {
             tools: toolInfo,
-            reccomendedPrompts: toolboxes.map((toolbox) => toolbox.recommendedPrompt),
+            reccomendedPrompts,
+            schemaVersion: (0, toolDiscovery_1.computeToolDiscoverySchemaVersion)({
+                tools: toolInfo,
+                reccomendedPrompts,
+            }),
         };
         const processedResponse = await processPluginsForResponse(response, body, { extraData: { plugins: processedPluginData.plugins } });
         return c.json(processedResponse);
@@ -846,6 +1156,10 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                 outputSchema: (0, schemaStructure_1.getDetailedSchemaStructure)(tool.output),
                 interface: tool.interface,
                 suggestConfirmation: tool.suggestConfirmation,
+                sideEffectClass: tool.sideEffectClass,
+                supportsParallel: tool.supportsParallel,
+                idempotencyScope: tool.idempotencyScope,
+                maxConcurrencyHint: tool.maxConcurrencyHint,
             };
             return c.json(toolDetails);
         }
@@ -873,6 +1187,11 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                             pricing: tool.pricing,
                             inputSchema: (0, schemaStructure_1.getDetailedSchemaStructure)(tool.input),
                             outputSchema: (0, schemaStructure_1.getDetailedSchemaStructure)(tool.output),
+                            suggestConfirmation: tool.suggestConfirmation,
+                            sideEffectClass: tool.sideEffectClass,
+                            supportsParallel: tool.supportsParallel,
+                            idempotencyScope: tool.idempotencyScope,
+                            maxConcurrencyHint: tool.maxConcurrencyHint,
                         }
                         : {
                             id: toolId,
@@ -898,7 +1217,13 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
         }
     });
     // Health check endpoint
-    app.get("/health", (c) => c.json({ status: "healthy", timestamp: new Date().toISOString() }));
+    app.get("/health", async (c) => {
+        const healthy = await resolveHealthStatus();
+        return c.json({
+            status: healthy ? "healthy" : "unhealthy",
+            timestamp: new Date().toISOString(),
+        }, healthy ? 200 : 503);
+    });
     // Setup custom routes if provided
     if (config.routes) {
         config.routes(app);
@@ -1182,64 +1507,231 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
     });
     // Toolboxes list endpoint
     app.get("/toolboxes", (c) => c.json(toolboxes));
-    // Recommendations endpoint - returns cards for AI selection
-    app.get("/recommendations", (c) => {
-        const cards = [];
+    function normalizeRecommendationText(value) {
+        return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    }
+    function tokenizeRecommendationQuery(query) {
+        const normalized = normalizeRecommendationText(query);
+        if (!normalized)
+            return [];
+        return Array.from(new Set(normalized.split(/\s+/).filter((token) => token.length >= 2)));
+    }
+    function buildRecommendationIndex() {
+        const index = new Map();
         for (const tool of tools) {
-            if (tool.recommendations?.length) {
-                for (const card of tool.recommendations) {
-                    const hasDynamicSchema = !!card.inputSchema;
-                    cards.push({
-                        id: card.id,
-                        tags: card.tags,
-                        ui: hasDynamicSchema ? undefined : card.ui,
-                        inputSchema: hasDynamicSchema ? (0, schemaStructure_1.zodToJsonSchema)(card.inputSchema) : undefined,
-                        toolId: tool.id,
-                        toolName: tool.name,
-                    });
+            if (!tool.recommendations?.length)
+                continue;
+            for (const card of tool.recommendations) {
+                const scopedCardId = `${tool.id}:${card.id}`;
+                if (index.has(scopedCardId)) {
+                    throw new Error(`Duplicate recommendation card ID "${scopedCardId}". Card IDs must be unique per tool.`);
                 }
+                const isDynamic = !!card.inputSchema;
+                const inputSchema = isDynamic ? (0, schemaStructure_1.zodToJsonSchema)(card.inputSchema) : undefined;
+                const searchText = normalizeRecommendationText([tool.id, tool.name, card.id, ...card.tags].join(" "));
+                index.set(scopedCardId, {
+                    cardId: scopedCardId,
+                    localCardId: card.id,
+                    toolId: tool.id,
+                    toolName: tool.name,
+                    tags: card.tags,
+                    inputSchema,
+                    ui: isDynamic ? undefined : card.ui,
+                    isDynamic,
+                    card,
+                    searchText,
+                });
             }
         }
-        return c.json({ cards, count: cards.length });
-    });
-    // Generate recommendation card UI
-    app.post("/recommendations/:id/generate", async (c) => {
-        const cardId = c.req.param("id");
-        const body = await c.req.json().catch(() => ({}));
-        const params = body.params ?? {};
-        const context = body.context ?? {};
-        let foundCard;
-        let foundTool;
-        for (const tool of tools) {
-            const card = tool.recommendations?.find((r) => r.id === cardId);
-            if (card) {
-                foundCard = card;
-                foundTool = tool;
-                break;
+        return index;
+    }
+    function scoreRecommendationCard(card, tokens) {
+        if (tokens.length === 0)
+            return 0;
+        let score = 0;
+        const tagSet = new Set(card.tags.map((tag) => normalizeRecommendationText(tag)));
+        const scopedId = normalizeRecommendationText(card.cardId);
+        const toolName = normalizeRecommendationText(card.toolName);
+        for (const token of tokens) {
+            if (scopedId === token || card.localCardId.toLowerCase() === token) {
+                score += 6;
+                continue;
+            }
+            if (tagSet.has(token)) {
+                score += 4;
+            }
+            if (toolName.includes(token)) {
+                score += 3;
+            }
+            if (card.searchText.includes(token)) {
+                score += 1;
             }
         }
-        if (!foundCard) {
-            return c.json({ error: `Card not found: ${cardId}` }, 404);
-        }
-        const baseResponse = { id: cardId, toolId: foundTool?.id, toolName: foundTool?.name };
-        if (!foundCard.inputSchema) {
-            return c.json({ ...baseResponse, ui: foundCard.ui });
-        }
-        const parseResult = foundCard.inputSchema.safeParse(params);
-        if (!parseResult.success) {
-            return c.json({ error: "Invalid parameters", details: parseResult.error.format() }, 400);
-        }
-        if (typeof foundCard.ui !== "function") {
-            return c.json({ error: `Card ${cardId} has inputSchema but ui is not a function` }, 500);
-        }
-        try {
-            const ui = await foundCard.ui(parseResult.data, context);
-            return c.json({ ...baseResponse, ui, params: parseResult.data });
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : "Unknown error";
-            return c.json({ error: `Failed to generate UI: ${message}` }, 500);
+        return score;
+    }
+    const recommendationCardsById = buildRecommendationIndex();
+    const recommendationSearchSchema = zod_1.z.object({
+        query: zod_1.z.string().optional(),
+        limit: zod_1.z.number().int().min(1).max(50).optional().default(12),
+        toolIds: zod_1.z.array(zod_1.z.string()).optional(),
+        includeStaticUI: zod_1.z.boolean().optional().default(false),
+    });
+    app.post("/recommendations/search", async (c) => {
+        const agentInfo = await getAgentInfo(c);
+        const body = await safeParseBody(c);
+        const processedPluginData = await processPluginsForRequest(body, agentInfo);
+        const requestData = { ...processedPluginData };
+        delete requestData.plugins;
+        const parsed = recommendationSearchSchema.safeParse(requestData);
+        if (!parsed.success) {
+            return c.json({
+                error: "Invalid recommendation search request",
+                details: parsed.error.format(),
+            }, 400);
+        }
+        const { query, limit, toolIds, includeStaticUI, } = parsed.data;
+        const toolIdSet = toolIds?.length ? new Set(toolIds) : null;
+        const filteredCards = Array.from(recommendationCardsById.values()).filter((card) => !toolIdSet || toolIdSet.has(card.toolId));
+        const tokens = tokenizeRecommendationQuery(query ?? "");
+        const ranked = filteredCards
+            .map((card, index) => ({
+            ...card,
+            score: scoreRecommendationCard(card, tokens),
+            index,
+        }))
+            .sort((a, b) => {
+            if (tokens.length === 0)
+                return a.index - b.index;
+            if (b.score !== a.score)
+                return b.score - a.score;
+            if (a.toolName !== b.toolName)
+                return a.toolName.localeCompare(b.toolName);
+            return a.localCardId.localeCompare(b.localCardId);
+        })
+            .slice(0, limit);
+        const cards = ranked.map((card) => ({
+            cardId: card.cardId,
+            localCardId: card.localCardId,
+            toolId: card.toolId,
+            toolName: card.toolName,
+            tags: card.tags,
+            score: card.score,
+            inputSchema: card.inputSchema,
+            ui: includeStaticUI && !card.isDynamic ? card.ui : undefined,
+            isDynamic: card.isDynamic,
+        }));
+        const response = {
+            cards,
+            count: cards.length,
+            query,
+        };
+        const processedResponse = await processPluginsForResponse(response, body, { extraData: { plugins: processedPluginData.plugins } });
+        return c.json(processedResponse);
+    });
+    const recommendationRenderSchema = zod_1.z.object({
+        cards: zod_1.z
+            .array(zod_1.z.object({
+            cardId: zod_1.z.string().min(1),
+            params: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+            context: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+        }))
+            .min(1)
+            .max(8),
+        continueOnError: zod_1.z.boolean().optional().default(true),
+    });
+    app.post("/recommendations/render", async (c) => {
+        const agentInfo = await getAgentInfo(c);
+        const body = await safeParseBody(c);
+        const processedPluginData = await processPluginsForRequest(body, agentInfo);
+        const requestData = { ...processedPluginData };
+        delete requestData.plugins;
+        const parsed = recommendationRenderSchema.safeParse(requestData);
+        if (!parsed.success) {
+            return c.json({
+                error: "Invalid recommendation render request",
+                details: parsed.error.format(),
+            }, 400);
+        }
+        const { cards: requestedCards, continueOnError } = parsed.data;
+        const renderedCards = [];
+        const renderErrors = [];
+        for (const requested of requestedCards) {
+            const card = recommendationCardsById.get(requested.cardId);
+            if (!card) {
+                renderErrors.push({
+                    cardId: requested.cardId,
+                    code: "not_found",
+                    message: `Card not found: ${requested.cardId}`,
+                });
+                if (!continueOnError)
+                    break;
+                continue;
+            }
+            if (!card.isDynamic) {
+                renderedCards.push({
+                    cardId: card.cardId,
+                    localCardId: card.localCardId,
+                    toolId: card.toolId,
+                    toolName: card.toolName,
+                    tags: card.tags,
+                    ui: card.card.ui,
+                });
+                continue;
+            }
+            const paramsInput = requested.params ?? {};
+            const parseResult = card.card.inputSchema.safeParse(paramsInput);
+            if (!parseResult.success) {
+                renderErrors.push({
+                    cardId: card.cardId,
+                    code: "invalid_params",
+                    message: "Invalid parameters",
+                    details: parseResult.error.format(),
+                });
+                if (!continueOnError)
+                    break;
+                continue;
+            }
+            if (typeof card.card.ui !== "function") {
+                renderErrors.push({
+                    cardId: card.cardId,
+                    code: "render_failed",
+                    message: `Card "${card.cardId}" is dynamic but has no UI generator function`,
+                });
+                if (!continueOnError)
+                    break;
+                continue;
+            }
+            try {
+                const ui = await card.card.ui(parseResult.data, requested.context ?? {});
+                renderedCards.push({
+                    cardId: card.cardId,
+                    localCardId: card.localCardId,
+                    toolId: card.toolId,
+                    toolName: card.toolName,
+                    tags: card.tags,
+                    ui,
+                    params: parseResult.data,
+                });
+            }
+            catch (error) {
+                renderErrors.push({
+                    cardId: card.cardId,
+                    code: "render_failed",
+                    message: error instanceof Error ? error.message : "Failed to render recommendation card",
+                });
+                if (!continueOnError)
+                    break;
+            }
         }
+        const response = {
+            cards: renderedCards,
+            errors: renderErrors,
+            renderedCount: renderedCards.length,
+            requestedCount: requestedCards.length,
+        };
+        const processedResponse = await processPluginsForResponse(response, body, { extraData: { plugins: processedPluginData.plugins } });
+        const statusCode = !continueOnError && renderErrors.length > 0 ? 400 : 200;
+        return c.json(processedResponse, statusCode);
     });
     // Process request with plugins
     async function processPluginsForRequest(request, agentInfo) {
@@ -1420,6 +1912,7 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                     }
                     catch (error) {
                         console.error(`Error in stream for ${tool.id}:`, error);
+                        const safeMsg = sanitizeErrorMessage(error);
                         // Send an error result rather than letting the stream end without a response
                         try {
                             if (withContext) {
@@ -1427,8 +1920,8 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                                     event: 'result',
                                     data: JSON.stringify({
                                         toolResult: {
-                                            error: error.message || "Unknown error",
-                                            text: `Error: ${error.message || "Unknown error"}`,
+                                            error: safeMsg,
+                                            text: `Error: ${safeMsg}`,
                                             data: null,
                                             ui: null
                                         },
@@ -1441,8 +1934,8 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                                 await stream.writeSSE({
                                     event: 'result',
                                     data: JSON.stringify({
-                                        error: error.message || "Unknown error",
-                                        text: `Error: ${error.message || "Unknown error"}`,
+                                        error: safeMsg,
+                                        text: `Error: ${safeMsg}`,
                                         data: null,
                                         ui: null
                                     }),
@@ -1534,13 +2027,14 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                 }
                 catch (error) {
                     console.error(`Error executing tool ${tool.id} (non-streaming):`, error);
+                    const safeMsg = sanitizeErrorMessage(error);
                     // Return formatted error response to match streaming behavior
                     let errorResponse;
                     if (withContext) {
                         errorResponse = {
                             toolResult: {
-                                error: error.message || "Unknown error",
-                                text: `Error: ${error.message || "Unknown error"}`,
+                                error: safeMsg,
+                                text: `Error: ${safeMsg}`,
                                 data: null,
                                 ui: null
                             },
@@ -1549,8 +2043,8 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
                     }
                     else {
                         errorResponse = {
-                            error: error.message || "Unknown error",
-                            text: `Error: ${error.message || "Unknown error"}`,
+                            error: safeMsg,
+                            text: `Error: ${safeMsg}`,
                             data: null,
                             ui: null
                         };