Merge branch 'dev' into gcp-stuff

Author: mantrakp04

.github/workflows/lint-and-build.yaml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [latest]
+        node-version: [24]
 
     steps:
       - uses: actions/checkout@v6

AGENTS.md

@@ -108,6 +108,7 @@ To see all development ports, refer to the index.html of `apps/dev-launchpad/pub
 - Any design components you add or modify in the dashboard, update the Playground page accordingly to showcase the changes.
 - Unless very clearly equivalent from types, prefer explicit null/undefinedness checks over boolean checks, eg. `foo == null` instead of `!foo`.
 - Ensure **aggressively** that all code has low coupling and high cohesion. This is really important as it makes sure our code remains consistent and maintainable. Eagerly refactor things into better abstractions and look out for them actively.
+- Whenever you change the URL of a page in the docs (or remove one), add a redirect in the docs-mintlify/docs.json file to make sure we don't lose any SEO juice.
 
 ### Code-related
 - Use ES6 maps instead of records wherever you can.

apps/backend/src/app/api/latest/ai/query/[mode]/route.ts

@@ -1,4 +1,3 @@
-import { forwardToProduction } from "@/lib/ai/forward";
 import { selectModel } from "@/lib/ai/models";
 import { getFullSystemPrompt } from "@/lib/ai/prompts";
 import { requestBodySchema } from "@/lib/ai/schema";
@@ -7,7 +6,6 @@ import { listManagedProjectIds } from "@/lib/projects";
 import { SmartResponse } from "@/route-handlers/smart-response";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 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";
@@ -30,18 +28,6 @@ export const POST = createSmartRouteHandler({
       throw new StatusError(StatusError.BadRequest, `Invalid tool names in request.`);
     }
 
-    const apiKey = getEnvVariable("STACK_OPENROUTER_API_KEY");
-
-
-    if (apiKey === "FORWARD_TO_PRODUCTION") {
-      const prodResponse = await forwardToProduction(mode, body);
-      return {
-        statusCode: prodResponse.status,
-        bodyType: "response" as const,
-        body: prodResponse,
-      };
-    }
-
     const isAuthenticated = fullReq.auth != null;
     const { quality, speed, systemPrompt: systemPromptId, tools: toolNames, messages, projectId } = body;
 

apps/backend/src/app/api/latest/integrations/ai-proxy/[[...path]]/route.ts

@@ -1,10 +1,11 @@
+import { ALLOWED_MODEL_IDS } from "@/lib/ai/models";
 import { handleApiRequest } from "@/route-handlers/smart-route-handler";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import { NextRequest } from "next/server";
 
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
-const OPENROUTER_MODEL = "anthropic/claude-sonnet-4.6";
+const OPENROUTER_DEFAULT_MODEL = "anthropic/claude-sonnet-4.6";
 
 function sanitizeBody(raw: ArrayBuffer): Uint8Array {
   const text = new TextDecoder().decode(raw);
@@ -19,7 +20,9 @@ function sanitizeBody(raw: ArrayBuffer): Uint8Array {
     throw new StatusError(400, "Request body must be a JSON object");
   }
 
-  parsed.model = OPENROUTER_MODEL;
+  if (!parsed.model || !ALLOWED_MODEL_IDS.has(parsed.model)) {
+    parsed.model = OPENROUTER_DEFAULT_MODEL;
+  }
 
   // OpenRouter limits metadata.user_id to 128 characters
   if (parsed.metadata?.user_id && parsed.metadata.user_id.length > 128) {

apps/backend/src/lib/ai/forward.ts

@@ -1,5 +1,5 @@
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
-import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
+import { getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
 
 export type ModelQuality = "dumb" | "smart" | "smartest";
 export type ModelSpeed = "slow" | "fast";
@@ -48,9 +48,24 @@ const MODEL_SELECTION_MATRIX: Record<
   },
 };
 
+// All unique model IDs referenced in the selection matrix, plus sonnet as the proxy default
+export const ALLOWED_MODEL_IDS: ReadonlySet<string> = new Set([
+  "anthropic/claude-sonnet-4.6",
+  ...Object.values(MODEL_SELECTION_MATRIX).flatMap(quality =>
+    Object.values(quality).flatMap(speed =>
+      Object.values(speed).map(config => config.modelId)
+    )
+  ),
+]);
+
 export function createOpenRouterProvider() {
-  const apiKey = getEnvVariable("STACK_OPENROUTER_API_KEY");
-  return createOpenRouter({ apiKey });
+  const baseURL = getNodeEnvironment() === "development"
+    ? "http://localhost:8102/api/latest/integrations/ai-proxy/v1"
+    : "https://api.stack-auth.com/api/latest/integrations/ai-proxy/v1";
+  return createOpenRouter({
+    apiKey: "forwarded",
+    baseURL,
+  });
 }
 
 export function selectModel(

apps/backend/src/lib/ai/models.ts

@@ -4,13 +4,13 @@ import { getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
 /**
  * Creates an MCP client connected to the Stack Auth documentation server.
  *
- * In development: connects to local docs server at http://localhost:8104
+ * In development: connects to local docs server at http://localhost:8126
  * In production: connects to production docs server at https://mcp.stack-auth.com
  */
 export async function createDocsTools() {
   const mcpUrl =
     getNodeEnvironment() === "development"
-      ? new URL("/api/internal/mcp", "http://localhost:8104")
+      ? new URL("/api/internal/mcp", "http://localhost:8126")
       : new URL("/api/internal/mcp", "https://mcp.stack-auth.com");
 
   const stackAuthMcp = await createMCPClient({

apps/backend/src/lib/ai/tools/docs.ts

@@ -18,6 +18,13 @@ export function isSecureEmailPort(port: number | string) {
   return parsedPort === 465 || parsedPort === 2465;
 }
 
+function is4yzSMTPResponseCode(code: number | undefined) {
+  if (typeof code !== 'number') {
+    return false;
+  }
+  return code >= 400 && code < 500;
+}
+
 export type LowLevelEmailConfig = {
   host: string,
   port: number,
@@ -168,6 +175,16 @@ async function _lowLevelSendEmailWithoutRetries(options: LowLevelSendEmailOption
               message: 'Connection to email server was lost unexpectedly. This could be due to incorrect email server port configuration or a temporary network issue. Please verify your configuration and try again.',
             } as const);
           }
+          // 4yz error codes are considered temporary errors in SMTP, so they should be retried anyway
+          // This is fallback logic for a code we don't explicitly capture but should still be retryable and we have the code
+          if (is4yzSMTPResponseCode(responseCode)) {
+            return Result.error({
+              rawError: error,
+              errorType: 'TRANSIENT_NEGATIVE_COMPLETION_REPLY',
+              canRetry: true,
+              message: 'The email server returned a temporary error. Please try again later.' + getServerResponse(error),
+            } as const);
+          }
         }
 
         // ============ temporary error ============

apps/backend/src/lib/emails-low-level.tsx

@@ -77,7 +77,7 @@ describe("local emulator config", () => {
     await writeConfigToFile(absoluteFilePath, { auth: { allowLocalhost: true } });
 
     await expect(fs.readFile(mountedFilePath, "utf-8")).resolves.toBe(
-      `export const config = {\n  "auth": {\n    "allowLocalhost": true\n  }\n};\n`
+      `import type { StackConfig } from "@stackframe/js";\n\nexport const config: StackConfig = {\n  "auth": {\n    "allowLocalhost": true\n  }\n};\n`
     );
   });
 

apps/backend/src/lib/local-emulator.test.ts

@@ -1,4 +1,5 @@
 import { globalPrismaClient } from "@/prisma-client";
+import { detectImportPackageFromDir, renderConfigFileContent } from "@stackframe/stack-shared/dist/config-rendering";
 import { isValidConfig } from "@stackframe/stack-shared/dist/config/format";
 import { getEnvVariable } from "@stackframe/stack-shared/dist/utils/env";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
@@ -97,6 +98,7 @@ export async function writeConfigToFile(filePath: string, config: Record<string,
   } else {
     await fs.mkdir(dir, { recursive: true });
   }
-  const content = `export const config = ${JSON.stringify(config, null, 2)};\n`;
+  const importPackage = detectImportPackageFromDir(dir);
+  const content = renderConfigFileContent(config, importPackage);
   await fs.writeFile(resolvedPath, content, "utf-8");
 }