@dainprotocol/service-sdk 2.0.87 → 2.0.89

package/dist/service/server.js

@@ -9,6 +9,7 @@ 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");
@@ -32,6 +33,21 @@ function debugWarn(...args) {
         console.warn(...args);
     }
 }
+function getFirstForwardedValue(value) {
+    if (!value)
+        return undefined;
+    const first = value.split(",")[0]?.trim();
+    return first || undefined;
+}
+function normalizeForwardedPrefix(prefix) {
+    if (!prefix)
+        return undefined;
+    const trimmed = prefix.trim();
+    if (!trimmed || trimmed === "/")
+        return undefined;
+    const normalized = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return normalized.replace(/\/+$/, "");
+}
 /**
  * Safely parse JSON body from request, returning empty object on failure.
  */
@@ -63,23 +79,30 @@ 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);
                 // 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);
     });
@@ -159,11 +182,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) {
@@ -177,8 +196,9 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
         debugLog(`[Auth Middleware] JWT present: ${!!jwtToken}, API Key present: ${!!apiKey}`);
         if (jwtToken) {
             // JWT Authentication (Users)
-            // Auto-detect JWT audience from Host header (works with localhost, tunnels, production)
-            const host = c.req.header("x-forwarded-host") || c.req.header("host");
+            // Auto-detect JWT audience from forwarded headers (works with localhost, path-based tunnels, production)
+            const host = getFirstForwardedValue(c.req.header("x-forwarded-host")) ||
+                getFirstForwardedValue(c.req.header("host"));
             if (!host) {
                 throw new http_exception_1.HTTPException(400, { message: "Unable to determine service URL. Host header is required." });
             }
@@ -186,22 +206,33 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
             if (host.includes(' ') || host.includes('\n') || host.includes('\r')) {
                 throw new http_exception_1.HTTPException(400, { message: "Invalid Host header format" });
             }
-            const xForwardedProto = c.req.header("x-forwarded-proto");
-            const protocol = xForwardedProto || (host.includes("localhost") ? "http" : "https");
-            const jwtAudience = `${protocol}://${host}`;
+            const xForwardedProto = getFirstForwardedValue(c.req.header("x-forwarded-proto"));
+            const protocol = xForwardedProto === "http" || xForwardedProto === "https"
+                ? xForwardedProto
+                : (host.includes("localhost") || host.startsWith("127.") ? "http" : "https");
+            const forwardedPrefix = normalizeForwardedPrefix(getFirstForwardedValue(c.req.header("x-forwarded-prefix")));
+            const jwtAudiences = [`${protocol}://${host}`];
+            if (forwardedPrefix) {
+                jwtAudiences.push(`${protocol}://${host}${forwardedPrefix}`);
+            }
             const publicKeyOrUrl = config.jwtPublicKey || config.dainIdUrl || "https://id.dain.org";
             const issuer = config.jwtIssuer || "dainid-oauth";
             const result = await (0, auth_1.verifyJWT)(jwtToken, publicKeyOrUrl, {
                 issuer: issuer,
-                audience: jwtAudience,
+                audience: jwtAudiences,
             });
             if (!result.valid) {
                 throw new http_exception_1.HTTPException(401, { message: `JWT verification failed: ${result.error}` });
             }
             // Defense in depth: double-check audience claim
-            if (result.payload.aud !== jwtAudience) {
+            const tokenAudiences = Array.isArray(result.payload?.aud)
+                ? result.payload.aud
+                : [result.payload?.aud];
+            const expectedAudienceSet = new Set(jwtAudiences);
+            const audienceMatched = tokenAudiences.some((aud) => aud && expectedAudienceSet.has(aud));
+            if (!audienceMatched) {
                 throw new http_exception_1.HTTPException(403, {
-                    message: `JWT audience mismatch. Expected: ${jwtAudience}, Got: ${result.payload.aud}`
+                    message: `JWT audience mismatch. Expected one of: ${jwtAudiences.join(", ")}, Got: ${tokenAudiences.filter(Boolean).join(", ")}`
                 });
             }
             c.set('authMethod', 'jwt');
@@ -273,15 +304,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
@@ -300,6 +389,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,
             };
         });
@@ -400,14 +493,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 } });
@@ -448,8 +553,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);
     });
@@ -479,6 +595,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),
         };
     }
@@ -516,12 +638,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);
@@ -539,6 +681,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,
@@ -615,13 +900,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) => {
@@ -630,9 +925,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);
@@ -819,6 +1119,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);
         }
@@ -846,6 +1150,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,
@@ -871,7 +1180,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);
@@ -924,31 +1239,11 @@ function setupHttpServer(config, tools, services, toolboxes, metadata, privateKe
             }
             try {
                 await app.oauth2.handleCallback(code, state);
-                return c.html(`
-          <html>
-            <body>
-              <script>
-                window.opener.postMessage({ type: 'oauth2-success', provider: '${provider}' }, '*');
-                window.close();
-              </script>
-              <h1>Authentication successful! You can close this window.</h1>
-            </body>
-          </html>
-        `);
+                return c.html("<html><body><script>window.opener.postMessage({ type: 'oauth2-success', provider: '" + provider + "' }, '*');window.close();</script><h1>Authentication successful! You can close this window.</h1></body></html>");
             }
             catch (error) {
                 console.error("OAuth callback error:", error);
-                return c.html(`
-          <html>
-            <body>
-              <script>
-                window.opener.postMessage({ type: 'oauth2-error', provider: '${provider}', error: '${error.message}' }, '*');
-                window.close();
-              </script>
-              <h1>Authentication failed! You can close this window.</h1>
-            </body>
-          </html>
-        `);
+                return c.html("<html><body><script>window.opener.postMessage({ type: 'oauth2-error', provider: '" + provider + "', error: '" + error.message + "' }, '*');window.close();</script><h1>Authentication failed! You can close this window.</h1></body></html>");
             }
         });
         // Make oauth2Handler available to tools
@@ -1175,64 +1470,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) {