hexclave
diff --git a/‎.claude/CLAUDE-KNOWLEDGE.md‎
Lines changed: 6 additions & 0 deletions b/‎.claude/CLAUDE-KNOWLEDGE.md‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎apps/backend/src/app/api/latest/ai/query/[mode]/route.ts‎
Lines changed: 26 additions & 42 deletions b/‎apps/backend/src/app/api/latest/ai/query/[mode]/route.ts‎
Lines changed: 26 additions & 42 deletions
@@ -355,3 +355,9 @@ Then restart the dev server. This rebuilds all packages and generates the necess
 
 ## Q: How is backwards compatibility for the offer→product rename handled in the payments purchase APIs?
 A: API v1 requests are routed through the `v2beta1` migration. The migration wraps the latest handlers, accepts legacy `offer_id`/`offer_inline` request fields, translates product-related errors back to the old offer error codes/messages, and augments responses (like `validate-code`) with `offer`/`conflicting_group_offers` aliases alongside the new `product` fields. Newer API versions keep the product-only contract.
+
+## Q: How does `/api/v1/ai/query/generate` reject invalid AI tool names?
+A: Invalid `tools` entries are rejected by `requestBodySchema` in `apps/backend/src/lib/ai/schema.ts` via `yupString().oneOf(TOOL_NAMES)`, so the endpoint returns a structured `SCHEMA_ERROR` object mentioning `body.tools[n]` rather than a custom `"Invalid tool names"` string from handler logic.
+
+## Q: Why did the internal metrics E2E snapshots need to change in April 2026?
+A: The `/api/v1/internal/metrics` response now intentionally includes `analytics_overview.daily_anonymous_visitors_fallback`, `analytics_overview.anonymous_visitors_fallback`, and `active_users_by_country`. Those additions are reflected in `packages/stack-shared/src/interface/admin-metrics.ts` and the backend route, so the E2E snapshots must include them instead of treating them as regressions.
@@ -3,18 +3,19 @@ import { selectModel } from "@/lib/ai/models";
 import { getFullSystemPrompt } from "@/lib/ai/prompts";
 import { reviewMcpCall } from "@/lib/ai/qa-reviewer";
 import { requestBodySchema } from "@/lib/ai/schema";
-import { getTools, validateToolNames } from "@/lib/ai/tools";
+import { getTools } from "@/lib/ai/tools";
 import { getVerifiedQaContext } from "@/lib/ai/verified-qa";
 import { listManagedProjectIds } from "@/lib/projects";
 import { SmartResponse } from "@/route-handlers/smart-response";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { runAsynchronouslyAndWaitUntil } from "@/utils/background-tasks";
 import { validateImageAttachments } from "@stackframe/stack-shared/dist/ai/image-limits";
+import { ChatContent } from "@stackframe/stack-shared/dist/interface/admin-interface";
 import { yupMixed, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import { Json } from "@stackframe/stack-shared/dist/utils/json";
-import { generateText, ModelMessage, stepCountIs, streamText } from "ai";
+import { generateText, stepCountIs, streamText, type ModelMessage } from "ai";
 
 export const POST = createSmartRouteHandler({
   metadata: {
@@ -29,11 +30,6 @@ export const POST = createSmartRouteHandler({
   response: yupMixed<SmartResponse>().defined(),
   async handler({ params, body }, fullReq) {
     const { mode } = params;
-
-    if (!validateToolNames(body.tools)) {
-      throw new StatusError(StatusError.BadRequest, `Invalid tool names in request.`);
-    }
-
     const isAuthenticated = fullReq.auth != null;
     const { quality, speed, systemPrompt: systemPromptId, tools: toolNames, messages, projectId } = body;
 
@@ -79,11 +75,17 @@ export const POST = createSmartRouteHandler({
             ? 5
             : 5;
 
+    // Cast: the schema narrows role and leaves content as unknown, but the
+    // AI SDK accepts a superset (role: "system" etc.). We've intentionally
+    // excluded `system` at the schema layer to prevent prompt-injection via
+    // client-supplied system messages — see schema.ts.
+    const modelMessages = messages as unknown as ModelMessage[];
+
     if (mode === "stream") {
       const result = streamText({
         model,
         system: systemPrompt,
-        messages: messages as ModelMessage[],
+        messages: modelMessages,
         tools: toolsArg,
         stopWhen: stepCountIs(stepLimit),
       });
@@ -99,47 +101,29 @@ export const POST = createSmartRouteHandler({
       const result = await generateText({
         model,
         system: systemPrompt,
-        messages: messages as ModelMessage[],
+        messages: modelMessages,
         tools: toolsArg,
         abortSignal: controller.signal,
         stopWhen: stepCountIs(stepLimit),
       }).finally(() => clearTimeout(timeoutId));
 
-      const contentBlocks: Array<
-        | { type: "text", text: string }
-        | {
-            type: "tool-call",
-            toolName: string,
-            toolCallId: string,
-            args: Json,
-            argsText: string,
-            result: Json,
-          }
-      > = [];
-
-      result.steps.forEach((step) => {
+      const content: ChatContent = result.steps.flatMap((step) => {
+        const blocks: ChatContent = [];
         if (step.text) {
-          contentBlocks.push({
-            type: "text",
-            text: step.text,
-          });
+          blocks.push({ type: "text", text: step.text });
         }
-
-        const toolResultsByCallId = new Map(
-          step.toolResults.map((r) => [r.toolCallId, r])
-        );
-
-        step.toolCalls.forEach((toolCall) => {
-          const toolResult = toolResultsByCallId.get(toolCall.toolCallId);
-          contentBlocks.push({
+        const outById = new Map(step.toolResults.map((r) => [r.toolCallId, r.output as Json]));
+        for (const call of step.toolCalls) {
+          blocks.push({
             type: "tool-call",
-            toolName: toolCall.toolName,
-            toolCallId: toolCall.toolCallId,
-            args: toolCall.input,
-            argsText: JSON.stringify(toolCall.input),
-            result: (toolResult?.output ?? null) as Json,
+            toolName: call.toolName,
+            toolCallId: call.toolCallId,
+            args: call.input as Json,
+            argsText: JSON.stringify(call.input),
+            result: outById.get(call.toolCallId) ?? null,
           });
-        });
+        }
+        return blocks;
       });
 
       let responseConversationId: string | undefined;
@@ -152,7 +136,7 @@ export const POST = createSmartRouteHandler({
           ? firstUserMessage.content
           : JSON.stringify(firstUserMessage?.content ?? "");
 
-        const innerToolCallsJson = JSON.stringify(contentBlocks.filter(b => b.type === "tool-call"));
+        const innerToolCallsJson = JSON.stringify(content.filter(b => b.type === "tool-call"));
 
         const logPromise = logMcpCall({
           correlationId,
@@ -183,7 +167,7 @@ export const POST = createSmartRouteHandler({
         statusCode: 200,
         bodyType: "json" as const,
         body: {
-          content: contentBlocks,
+          content,
           finalText: result.text,
           conversationId: responseConversationId ?? null,
         },