@agent-native/core 0.80.0 → 0.80.2

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.80.0",
+  "version": "0.80.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/application-state/handlers.ts

@@ -33,7 +33,7 @@ async function getSessionId(event: H3Event): Promise<string> {
 }
 
 function safeKey(key: string): string {
-  return key.replace(/[^a-zA-Z0-9_:\-]/g, "");
+  return key.replace(/[^a-zA-Z0-9_:-]/g, "");
 }
 
 // --- Generic state handlers ---

package/corpus/core/src/brand-kit/index.ts

@@ -3,7 +3,7 @@
  *
  * The shared, template-agnostic Brand Kit surface. A Brand Kit unifies what
  * `design` and `slides` previously copy-pasted as a "design system": design
- * tokens + brand assets + custom instructions, extractable from Figma, code,
+ * tokens + brand assets + custom instructions, extractable from code,
  * GitHub, a URL, or documents, and used to generate on-brand content.
  *
  * This module is pure (no `defineAction`, no DB, no template imports). Templates

package/corpus/core/src/cli/skills.ts

@@ -404,6 +404,10 @@ iframe-backed screens on the infinite canvas.
   iframe frame and URL metadata; change the copy's path/query for a new state.
 - Flow visualization is multiple URL states: \`/checkout?step=shipping\`,
   \`/checkout?step=payment\`, \`/checkout?step=done\`, etc.
+- When the user gives a named flow or numbered screen list, preserve that order
+  and create one screen per URL/path. Shorthand like
+  \`localhost:1234/onboarding/1\` means
+  \`http://localhost:1234/onboarding/1\`.
 
 ## Required Local Bridge
 
@@ -439,6 +443,20 @@ pnpm action add-localhost-screens '{
 }'
 \`\`\`
 
+For a numbered flow the user describes in chat, keep the labels and order:
+
+\`\`\`bash
+pnpm action add-localhost-screens '{
+  "designId": "<design-id>",
+  "connectionId": "<connection-id>",
+  "routes": [
+    { "url": "localhost:1234/onboarding/1", "title": "Screen 1" },
+    { "url": "localhost:1234/onboarding/2", "title": "Screen 2" },
+    { "url": "localhost:1234/onboarding/3", "title": "Screen 3" }
+  ]
+}'
+\`\`\`
+
 If no \`routes\` or \`paths\` are supplied, \`add-localhost-screens\` uses every
 route from the latest localhost manifest.
 

package/corpus/core/src/client/AgentPanel.tsx

@@ -1318,7 +1318,7 @@ function AgentPanelInner({
             data-agent-page-new-chat=""
             aria-label={t("agentPanel.newChat")}
             onClick={() => {
-              void addTab();
+              addTab();
             }}
             className="pointer-events-auto inline-flex h-8 items-center gap-1.5 rounded-md border border-border bg-background/95 px-2.5 text-xs font-medium text-foreground shadow-sm backdrop-blur transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
           >

package/corpus/core/src/client/MultiTabAssistantChat.tsx

@@ -1625,7 +1625,7 @@ export function MultiTabAssistantChat({
               return next;
             });
             if (shouldRefreshThreads) {
-              void refreshThreads();
+              refreshThreads();
             }
           }
         }

package/corpus/core/src/client/extensions/portable-extension.ts

@@ -47,7 +47,7 @@ export interface AgentNativeExtensionStorageOptions {
 export interface AgentNativeExtensionStorageContext {
   extensionId: string;
   slotId?: string;
-  scope?: Exclude<AgentNativeExtensionStorageScope, "all"> | string;
+  scope?: Exclude<AgentNativeExtensionStorageScope, "all">;
   userId?: string;
   organizationId?: string;
   [key: string]: unknown;

package/corpus/core/src/code-agents/transcript-normalizer.ts

@@ -576,7 +576,7 @@ function joinAssistantChunks(previous: string, next: string): string {
   if (!next) return previous;
   if (/\s$/.test(previous) || /^\s/.test(next)) return `${previous}${next}`;
   if (/^[.,!?;:)\]}'"`]/.test(next)) return `${previous}${next}`;
-  if (/[(\[{'"`]$/.test(previous)) return `${previous}${next}`;
+  if (/[([{'"`]$/.test(previous)) return `${previous}${next}`;
   return `${previous} ${next}`;
 }
 

package/corpus/core/src/extensions/path.ts

@@ -19,10 +19,7 @@ export function extensionNameToSlug(
   return sliced || "extension";
 }
 
-export function extensionPath(
-  id: string,
-  name?: string | null | undefined,
-): string {
+export function extensionPath(id: string, name?: string | null): string {
   const encodedId = encodeURIComponent(id);
   if (name === undefined) return `/extensions/${encodedId}`;
   return `/extensions/${encodedId}/${extensionNameToSlug(name)}`;

package/corpus/core/src/integrations/a2a-continuation-processor.ts

@@ -528,7 +528,7 @@ function expandRelativeUrls(text: string, agentUrl: string): string {
   if (!text || !agentUrl) return text;
   const base = publicAgentBaseUrl(agentUrl);
   return text.replace(
-    /(^|[\s(\[<"'`])(\/[a-z0-9_-][a-z0-9_/?&=%#.,:-]*)/gi,
+    /(^|[\s([<"'`])(\/[a-z0-9_-][a-z0-9_/?&=%#.,:-]*)/gi,
     (_match, lead, path) => `${lead}${base}${path}`,
   );
 }

package/corpus/core/src/mcp/build-server.ts

@@ -750,7 +750,7 @@ function safeUiSegment(value: string | undefined, fallback: string): string {
 
 // ChatGPT and Claude cache MCP App resource HTML by `ui://` URI. Bump this
 // when the shared shell changes in a way that must invalidate host caches.
-const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v53";
+const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v54";
 
 function legacyDefaultMcpAppUri(config: MCPConfig, actionName: string): string {
   const app = safeUiSegment(config.appId ?? config.name, "agent-native");
@@ -1889,7 +1889,7 @@ async function isConnectTokenAllowed(
  */
 export async function verifyAuth(
   authHeader: string | undefined,
-  ownerEmailHeader?: string | undefined,
+  ownerEmailHeader?: string,
   options: { allowDevOpen?: boolean; resourceUrl?: string | string[] } = {},
 ): Promise<{
   authed: boolean;

package/corpus/core/src/mcp/embed-app.ts

@@ -124,6 +124,7 @@ export function embedApp(
     let app = null;
     let appConnectPromise = null;
     let openAiBridge = null;
+    let lastOpenAiSyncSignature = null;
     let wrapperRequestId = 0;
     const wrapperRequests = new Map();
     let toolInput = {};
@@ -1533,11 +1534,19 @@ export function embedApp(
         setMessage("Ready to open.");
         return;
       }
-      setMessage("Loading app");
       try {
         const selfNavigate = shouldSelfNavigateToApp();
         if (startedFor === launchUrl) return;
         startedFor = launchUrl;
+        // Only show the loading message when no frame is mounted yet. ChatGPT
+        // fires openai:set_globals (and thus re-launch) constantly; calling
+        // setMessage() unconditionally here wiped the just-mounted iframe out of
+        // the stage on every redundant launch, so the app rendered and was
+        // instantly blanked back to "Loading app" forever. renderFrame()/
+        // transplant replace the stage themselves when they actually (re)mount.
+        if (!appFrame) {
+          setMessage("Loading app");
+        }
         const embedUrl = withChatBridgeParam(launchUrl);
         if (selfNavigate && isEmbedStartUrl(embedUrl)) {
           if (shouldTransplantAppDocument()) {
@@ -1662,6 +1671,31 @@ export function embedApp(
       toolResultData = objectValue(data);
       openUrl = openLinkFrom(params, data);
       openStartUrl = embedStartUrlFrom(params, data);
+      // ChatGPT/Codex fire openai:set_globals extremely often, and the listener
+      // that calls this re-syncs on each one. Because this function calls
+      // notifyHostHeight()/sendHostContext() (which the host reflects back as a
+      // fresh set_globals), an unguarded sync becomes an infinite feedback storm
+      // that starves the host until it shows its sad-face placeholder. Only do
+      // the host round-trips + (re)launch when something we care about changed.
+      // Deliberately EXCLUDE bridge.maxHeight: the host mutates it on every
+      // set_globals as it echoes our height back, which would defeat the guard.
+      let signature;
+      try {
+        signature = JSON.stringify([
+          toolInput,
+          openUrl,
+          openStartUrl,
+          bridge.displayMode,
+          bridge.theme,
+          bridge.locale
+        ]);
+      } catch {
+        signature = null;
+      }
+      if (signature !== null && signature === lastOpenAiSyncSignature) {
+        return true;
+      }
+      lastOpenAiSyncSignature = signature;
       updateTitle(data);
       updateOpenButton();
       updateDisplayButton();

package/corpus/core/src/org/handlers.ts

@@ -17,8 +17,8 @@ function extractInvitationId(event: H3Event): string | undefined {
   if (fromRouter) return fromRouter;
   const path = getRequestURL(event).pathname;
   const match =
-    path.match(/^\/([^\/]+)\/accept\/?$/) ??
-    path.match(/\/org\/invitations\/([^\/]+)\/accept\/?$/);
+    path.match(/^\/([^/]+)\/accept\/?$/) ??
+    path.match(/\/org\/invitations\/([^/]+)\/accept\/?$/);
   return match?.[1] ? decodeURIComponent(match[1]) : undefined;
 }
 
@@ -28,9 +28,9 @@ function extractMemberEmail(event: H3Event): string | undefined {
   if (fromRouter) return fromRouter;
   const path = getRequestURL(event).pathname;
   const match =
-    path.match(/^\/([^\/]+)\/role\/?$/) ??
-    path.match(/^\/([^\/]+)\/?$/) ??
-    path.match(/\/org\/members\/([^\/]+)(?:\/role)?\/?$/);
+    path.match(/^\/([^/]+)\/role\/?$/) ??
+    path.match(/^\/([^/]+)\/?$/) ??
+    path.match(/\/org\/members\/([^/]+)(?:\/role)?\/?$/);
   return match?.[1] ? decodeURIComponent(match[1]) : undefined;
 }
 const nanoid = (): string =>

package/corpus/core/src/org/plugin.ts

@@ -100,7 +100,7 @@ export function createOrgPlugin(): NitroPluginDef {
           return listMembersHandler(event);
         }
         // Tail is /:email/role
-        if (/^\/[^\/]+\/role\/?$/.test(tail)) {
+        if (/^\/[^/]+\/role\/?$/.test(tail)) {
           if (method !== "PUT") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
@@ -129,7 +129,7 @@ export function createOrgPlugin(): NitroPluginDef {
           return { error: "Method not allowed" };
         }
         // Tail is /:id/accept
-        if (/^\/[^\/]+\/accept\/?$/.test(tail)) {
+        if (/^\/[^/]+\/accept\/?$/.test(tail)) {
           if (method !== "POST") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };

package/corpus/core/src/scripts/call-agent.ts

@@ -434,7 +434,7 @@ export function expandRelativeUrls(text: string, agentUrl: string): string {
   // Path must start at boundary (start, whitespace, or punctuation that isn't
   // ':' — to avoid mangling `https://example.com/foo` or markdown link bodies).
   return text.replace(
-    /(^|[\s(\[<"'`])(\/[a-z0-9_-][a-z0-9_/?&=%#.,:-]*)/gi,
+    /(^|[\s([<"'`])(\/[a-z0-9_-][a-z0-9_/?&=%#.,:-]*)/gi,
     (_match, lead, path) => `${lead}${base}${path}`,
   );
 }

package/corpus/core/src/scripts/db/safety.ts

@@ -171,7 +171,7 @@ const ACCESS_CONTROL_COLUMN_TOKENS = new Set([
 function normalizeIdentifier(value: string): string {
   return value
     .trim()
-    .replace(/^["'`\[]/, "")
+    .replace(/^["'`[]/, "")
     .replace(/["'`\]]$/, "")
     .toLowerCase();
 }

package/corpus/core/src/server/auth.ts

@@ -1855,6 +1855,9 @@ function createAuthGuardFn(): (
     // the gate below 401s anonymous /_agent-native/* requests before any DB
     // query, so the database would never get warmed.
     if (p === "/_agent-native/health") return;
+    if (getMethod(event) === "GET" && p.startsWith("/_agent-native/avatar/")) {
+      return;
+    }
     if (isPublicPath(normalizedUrl, publicPaths)) return;
     if (shouldBypassAuthForBuilderConnect(event, p)) return;
     if (isPublicWorkspacePageRequest(event, p, config)) {

package/corpus/core/src/server/builder-design-systems.ts

@@ -0,0 +1,308 @@
+import { FeatureNotConfiguredError } from "./credential-provider.js";
+import {
+  getBuilderProxyOrigin,
+  resolveBuilderCredentials,
+} from "./credential-provider.js";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface BuilderDesignSystemIndexFile {
+  name: string;
+  data: Uint8Array;
+  mimeType?: string;
+}
+
+export interface BuilderDesignSystemIndexOptions {
+  projectName?: string;
+  description?: string;
+  githubRepoUrl?: string;
+  connectedProjectId?: string;
+  files?: BuilderDesignSystemIndexFile[];
+  selection?: Record<string, string[]>;
+  devToolsVersion?: string;
+}
+
+export interface BuilderDesignSystemIndexResult {
+  ok: true;
+  source: "builder";
+  projectId: string;
+  jobId: string;
+  designSystemId: string;
+  suggestedTitle: string | null;
+  builderUrl: string;
+  status: "in-progress";
+}
+
+interface BuilderDesignSystemCredentials {
+  privateKey: string;
+  publicKey: string;
+  userId: string | null;
+}
+
+interface UploadStartResponse {
+  uploads?: Array<{ idx: number; uploadUrl: string; uploadToken: string }>;
+}
+
+interface GenerateResponse {
+  projectId?: string;
+  jobId?: string;
+  designSystemId?: string;
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, "");
+}
+
+export function getBuilderDesignSystemsBaseUrl(): string {
+  return (
+    process.env.BUILDER_DESIGN_SYSTEMS_BASE_URL ||
+    `${trimTrailingSlash(getBuilderProxyOrigin())}/design-systems/v1`
+  );
+}
+
+function getBuilderAppHost(): string {
+  return (
+    process.env.BUILDER_APP_HOST ||
+    process.env.BUILDER_PUBLIC_APP_HOST ||
+    "https://builder.io"
+  );
+}
+
+function makeBuilderDesignSystemUrl(
+  path: string,
+  credentials: BuilderDesignSystemCredentials,
+): URL {
+  const base = `${trimTrailingSlash(getBuilderDesignSystemsBaseUrl())}/`;
+  const url = new URL(path.replace(/^\/+/, ""), base);
+  url.searchParams.set("apiKey", credentials.publicKey);
+  if (credentials.userId) url.searchParams.set("userId", credentials.userId);
+  return url;
+}
+
+function makeBuilderHeaders(
+  credentials: BuilderDesignSystemCredentials,
+): Record<string, string> {
+  return {
+    Authorization: `Bearer ${credentials.privateKey}`,
+    "x-builder-api-key": credentials.publicKey,
+    ...(credentials.userId ? { "x-builder-user-id": credentials.userId } : {}),
+  };
+}
+
+async function resolveBuilderDesignSystemCredentials(): Promise<BuilderDesignSystemCredentials> {
+  const credentials = await resolveBuilderCredentials();
+  if (!credentials.privateKey || !credentials.publicKey) {
+    throw new FeatureNotConfiguredError({
+      requiredCredential: "BUILDER_PRIVATE_KEY",
+      message:
+        "Connect Builder.io before indexing a design system from Figma or code.",
+      builderConnectUrl: "/_agent-native/builder/connect",
+    });
+  }
+  return {
+    privateKey: credentials.privateKey,
+    publicKey: credentials.publicKey,
+    userId: credentials.userId ?? null,
+  };
+}
+
+function mimeTypeForFile(file: BuilderDesignSystemIndexFile): string {
+  if (file.mimeType?.trim()) return file.mimeType.trim();
+  const lower = file.name.toLowerCase();
+  if (lower.endsWith(".fig")) return "application/octet-stream";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  if (lower.endsWith(".md") || lower.endsWith(".markdown"))
+    return "text/markdown";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".css")) return "text/css";
+  return "text/plain";
+}
+
+function makeBody(bytes: Uint8Array, mimeType: string): BodyInit {
+  return typeof Blob !== "undefined"
+    ? new Blob([bytes as unknown as BlobPart], { type: mimeType })
+    : (bytes as unknown as BodyInit);
+}
+
+async function fetchWithTimeout(
+  url: string | URL,
+  init: RequestInit,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function parseErrorBody(response: Response): Promise<string> {
+  const text = await response.text().catch(() => "");
+  if (!text) return response.statusText || `HTTP ${response.status}`;
+  try {
+    const json = JSON.parse(text) as { error?: unknown };
+    if (typeof json.error === "string") return json.error;
+    if (json.error && typeof json.error === "object") {
+      return JSON.stringify(json.error).slice(0, 500);
+    }
+  } catch {}
+  return text.replace(/\s+/g, " ").trim().slice(0, 500);
+}
+
+async function assertOk(response: Response, label: string): Promise<void> {
+  if (response.ok) return;
+  throw new Error(
+    `${label} (${response.status}): ${await parseErrorBody(response)}`,
+  );
+}
+
+async function uploadToResumableUrl(
+  slot: { uploadUrl: string },
+  file: BuilderDesignSystemIndexFile,
+): Promise<void> {
+  const mimeType = mimeTypeForFile(file);
+  const bytes = file.data;
+  const start = await fetchWithTimeout(slot.uploadUrl, {
+    method: "POST",
+    headers: {
+      "x-goog-resumable": "start",
+      "x-goog-content-length-range": `0,${bytes.byteLength}`,
+      "Content-Type": mimeType,
+    },
+  });
+  await assertOk(start, "Builder design-system upload session failed");
+  const sessionUrl = start.headers.get("Location");
+  if (!sessionUrl) {
+    throw new Error("Builder design-system upload session returned no URL.");
+  }
+
+  const response = await fetchWithTimeout(sessionUrl, {
+    method: "PUT",
+    headers: {
+      "Content-Range": `bytes 0-${bytes.byteLength - 1}/${bytes.byteLength}`,
+      "Content-Type": mimeType,
+    },
+    body: makeBody(bytes, mimeType),
+  });
+  await assertOk(response, "Builder design-system file upload failed");
+}
+
+function nonEmptyFiles(
+  files: BuilderDesignSystemIndexFile[] | undefined,
+): BuilderDesignSystemIndexFile[] {
+  return (files ?? []).filter((file) => file.data.byteLength > 0);
+}
+
+export function builderDesignSystemUrl(designSystemId?: string | null): string {
+  const host = trimTrailingSlash(getBuilderAppHost());
+  return designSystemId
+    ? `${host}/app/design-system-intelligence/${encodeURIComponent(
+        designSystemId,
+      )}`
+    : `${host}/app/design-system-intelligence`;
+}
+
+export async function startBuilderDesignSystemIndex(
+  options: BuilderDesignSystemIndexOptions,
+): Promise<BuilderDesignSystemIndexResult> {
+  const files = nonEmptyFiles(options.files);
+  const description = options.description?.trim();
+  if (description) {
+    files.unshift({
+      name: "additional-context.txt",
+      data: new TextEncoder().encode(description),
+      mimeType: "text/plain",
+    });
+  }
+  if (
+    files.length === 0 &&
+    !options.githubRepoUrl &&
+    !options.connectedProjectId
+  ) {
+    throw new Error(
+      "Provide at least one .fig/code/text file or a GitHub repository URL to index with Builder.",
+    );
+  }
+
+  const credentials = await resolveBuilderDesignSystemCredentials();
+  let uploadTokens: string[] = [];
+  if (files.length > 0) {
+    const uploadStart = await fetchWithTimeout(
+      makeBuilderDesignSystemUrl("upload/start", credentials),
+      {
+        method: "POST",
+        headers: {
+          ...makeBuilderHeaders(credentials),
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          attachments: files.map((file) => ({
+            name: file.name,
+            mimetype: mimeTypeForFile(file),
+            declaredSize: file.data.byteLength,
+          })),
+        }),
+      },
+    );
+    await assertOk(uploadStart, "Builder design-system upload start failed");
+    const uploadJson = (await uploadStart.json()) as UploadStartResponse;
+    const slots = [...(uploadJson.uploads ?? [])].sort((a, b) => a.idx - b.idx);
+    if (slots.length !== files.length) {
+      throw new Error("Builder did not return upload slots for all files.");
+    }
+    for (let i = 0; i < slots.length; i++) {
+      if (slots[i].idx !== i) {
+        throw new Error(`Builder upload slot mismatch: expected ${i}.`);
+      }
+      await uploadToResumableUrl(slots[i], files[i]);
+    }
+    uploadTokens = slots.map((slot) => slot.uploadToken);
+  }
+
+  const generate = await fetchWithTimeout(
+    makeBuilderDesignSystemUrl("generate", credentials),
+    {
+      method: "POST",
+      headers: {
+        ...makeBuilderHeaders(credentials),
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        uploads: uploadTokens,
+        ...(options.projectName?.trim()
+          ? { projectName: options.projectName.trim() }
+          : {}),
+        ...(options.githubRepoUrl?.trim()
+          ? { githubRepoUrl: options.githubRepoUrl.trim() }
+          : {}),
+        ...(options.connectedProjectId?.trim()
+          ? { connectedProjectId: options.connectedProjectId.trim() }
+          : {}),
+        ...(options.selection ? { selection: options.selection } : {}),
+        ...(options.devToolsVersion?.trim()
+          ? { devToolsVersion: options.devToolsVersion.trim() }
+          : {}),
+      }),
+    },
+  );
+  await assertOk(generate, "Builder design-system indexing failed");
+  const generated = (await generate.json()) as GenerateResponse;
+  if (!generated.projectId || !generated.jobId || !generated.designSystemId) {
+    throw new Error(
+      "Builder design-system indexing returned an incomplete response.",
+    );
+  }
+
+  return {
+    ok: true,
+    source: "builder",
+    projectId: generated.projectId,
+    jobId: generated.jobId,
+    designSystemId: generated.designSystemId,
+    suggestedTitle: options.projectName?.trim() || null,
+    builderUrl: builderDesignSystemUrl(generated.designSystemId),
+    status: "in-progress",
+  };
+}

package/corpus/core/src/server/core-routes-plugin.ts

@@ -383,6 +383,31 @@ function parseBuilderCallbackBoolean(
 // inlines them in the DOM. Mirrors SAFE_DATA_IMAGE in sanitize-html.ts.
 export const AVATAR_RASTER_MIME = /^data:image\/(png|jpe?g|gif|webp);/i;
 
+export function resolveAvatarEmailParam(
+  pathname: string,
+  appBasePath = "",
+): string {
+  const base = appBasePath.replace(/\/+$/, "");
+  const avatarPaths = Array.from(
+    new Set([`${base}/_agent-native/avatar/`, "/_agent-native/avatar/"]),
+  );
+
+  for (const avatarPath of avatarPaths) {
+    const avatarIndex = pathname.indexOf(avatarPath);
+    if (avatarIndex >= 0) {
+      return pathname
+        .slice(avatarIndex + avatarPath.length)
+        .replace(/^\/+/, "")
+        .split("/")[0];
+    }
+  }
+
+  const firstSegment = pathname.replace(/^\/+/, "").split("/")[0] ?? "";
+  if (!firstSegment || firstSegment === "_agent-native") return "";
+  if (base && firstSegment === base.replace(/^\/+/, "")) return "";
+  return firstSegment;
+}
+
 async function detectUsageEngineName(
   event: H3Event,
   userEmail: string | undefined,
@@ -3010,9 +3035,10 @@ export function createCoreRoutesPlugin(
         `${P}/avatar`,
         defineEventHandler(async (event: H3Event) => {
           const method = getMethod(event);
-          const emailParam = (event.url?.pathname || "")
-            .replace(/^\/+/, "")
-            .split("/")[0];
+          const emailParam = resolveAvatarEmailParam(
+            event.url?.pathname || "",
+            getConfiguredAppBasePath(),
+          );
 
           if (method === "GET") {
             if (!emailParam) {

package/corpus/core/src/server/index.ts

@@ -386,6 +386,14 @@ export {
   deleteBuilderCredentials,
   resolveSecret,
 } from "./credential-provider.js";
+export {
+  builderDesignSystemUrl,
+  getBuilderDesignSystemsBaseUrl,
+  startBuilderDesignSystemIndex,
+  type BuilderDesignSystemIndexFile,
+  type BuilderDesignSystemIndexOptions,
+  type BuilderDesignSystemIndexResult,
+} from "./builder-design-systems.js";
 export {
   getBuilderBranchProjectId,
   isBuilderBranchingEnabled,