@agent-native/core 0.79.21 → 0.79.22

package/corpus/core/src/client/settings/SettingsPanel.tsx

@@ -1,6 +1,7 @@
 import * as SelectPrimitive from "@radix-ui/react-select";
 import {
   IconChevronDown,
+  IconChevronRight,
   IconCheck,
   IconExternalLink,
   IconBrain,
@@ -33,7 +34,7 @@ import React, {
 } from "react";
 
 import { PROVIDER_ENV_PLACEHOLDERS } from "../../agent/engine/provider-env-vars.js";
-import { saveAgentEngineApiKey } from "../agent-engine-key.js";
+import { saveAgentEngineProviderSettings } from "../agent-engine-key.js";
 import { agentNativePath } from "../api-path.js";
 import { BuilderBMark } from "../builder-mark.js";
 import {
@@ -619,6 +620,10 @@ function LLMSectionInner({
   const [currentModel, setCurrentModel] = useState("");
   const [selectedEngine, setSelectedEngine] = useState("anthropic");
   const [selectedModel, setSelectedModel] = useState("");
+  const [baseUrl, setBaseUrl] = useState("");
+  const [baseUrlConfigured, setBaseUrlConfigured] = useState(false);
+  const [clearBaseUrl, setClearBaseUrl] = useState(false);
+  const [advancedOpen, setAdvancedOpen] = useState(false);
   const [applyNote, setApplyNote] = useState(false);
   const [testing, setTesting] = useState(false);
   const [testResult, setTestResult] = useState<
@@ -651,6 +656,7 @@ function LLMSectionInner({
     fetch(agentNativePath("/_agent-native/agent-engine/status"))
       .then((r) => (r.ok ? r.json() : null))
       .then((data) => {
+        setBaseUrlConfigured(Boolean(data?.openAiBaseUrlConfigured));
         if (
           data?.configured &&
           typeof data.engine === "string" &&
@@ -715,6 +721,9 @@ function LLMSectionInner({
 
   const engineChanged =
     selectedEngine !== currentEngine || selectedModel !== currentModel;
+  const isOpenAiEngine = selectedEngine === "ai-sdk:openai";
+  const endpointChanged = isOpenAiEngine && (!!baseUrl.trim() || clearBaseUrl);
+  const providerSettingsChanged = !!apiKey.trim() || endpointChanged;
 
   // Hide the Anthropic-via-AI-SDK alias (redundant with the native entry)
   // and Ollama (no API key to set here). The currently-selected engine is
@@ -732,12 +741,22 @@ function LLMSectionInner({
   ).map((m) => ({ value: m, label: friendlyModelName(m) }));
 
   const handleSave = async () => {
-    if (!apiKey.trim() || !envVar) return;
+    if (!providerSettingsChanged || !envVar) return;
     setSaving(true);
     try {
-      await saveAgentEngineApiKey({ key: envVar, apiKey });
+      const nextBaseUrl = isOpenAiEngine ? baseUrl.trim() : "";
+      await saveAgentEngineProviderSettings({
+        key: envVar,
+        ...(apiKey.trim() ? { apiKey } : {}),
+        ...(nextBaseUrl ? { baseUrl: nextBaseUrl } : {}),
+        ...(isOpenAiEngine && clearBaseUrl ? { clearBaseUrl: true } : {}),
+      });
       setSaved(true);
       setApiKey("");
+      setBaseUrl("");
+      setClearBaseUrl(false);
+      if (nextBaseUrl) setBaseUrlConfigured(true);
+      if (clearBaseUrl) setBaseUrlConfigured(false);
       refreshSettingsStatus();
       notifyConfigChanged();
       setTimeout(() => setSaved(false), 2000);
@@ -885,6 +904,9 @@ function LLMSectionInner({
                     const info = engines.find((e) => e.name === val);
                     setSelectedModel(info?.defaultModel ?? "");
                     setApiKey("");
+                    setBaseUrl("");
+                    setClearBaseUrl(false);
+                    setAdvancedOpen(false);
                   }}
                 />
 
@@ -920,6 +942,99 @@ function LLMSectionInner({
                   )}
                 </div>
 
+                {isOpenAiEngine && (
+                  <div className="border-t border-border/70 pt-2">
+                    <button
+                      type="button"
+                      onClick={() => setAdvancedOpen((v) => !v)}
+                      className="flex w-full cursor-pointer items-center justify-between gap-2 rounded px-0.5 py-1 text-left hover:text-foreground"
+                    >
+                      <span className="inline-flex min-w-0 items-center gap-1.5 text-[11px] font-medium text-foreground">
+                        {advancedOpen ? (
+                          <IconChevronDown size={12} />
+                        ) : (
+                          <IconChevronRight
+                            size={12}
+                            className="rtl:-scale-x-100"
+                          />
+                        )}
+                        Advanced
+                      </span>
+                      <span className="truncate text-[10px] text-muted-foreground">
+                        OpenAI-compatible endpoint
+                      </span>
+                    </button>
+
+                    {advancedOpen && (
+                      <div className="mt-1.5 space-y-1.5">
+                        <div className="flex items-center justify-between gap-2">
+                          <p className="text-[12px] font-medium text-foreground">
+                            Endpoint URL
+                          </p>
+                          <span className="text-[10px] text-muted-foreground">
+                            {baseUrlConfigured ? "Configured" : "Optional"}
+                          </span>
+                        </div>
+                        <input
+                          type="url"
+                          value={baseUrl}
+                          onChange={(e) => {
+                            setBaseUrl(e.target.value);
+                            if (e.target.value.trim()) setClearBaseUrl(false);
+                          }}
+                          onKeyDown={(e) => {
+                            if (e.key === "Enter") handleSave();
+                          }}
+                          placeholder={
+                            baseUrlConfigured
+                              ? "Leave blank to keep current endpoint"
+                              : "https://gateway.example/v1"
+                          }
+                          disabled={clearBaseUrl}
+                          spellCheck={false}
+                          autoComplete="off"
+                          className="flex h-9 w-full rounded-md border border-border bg-background px-3 text-[12px] text-foreground outline-none transition-colors hover:bg-accent/40 focus:ring-1 focus:ring-accent disabled:opacity-50 placeholder:text-muted-foreground/50"
+                          style={CONTROL_STYLE}
+                        />
+                        <p className="text-[10px] leading-relaxed text-muted-foreground">
+                          Use for LiteLLM or another OpenAI-compatible chat
+                          gateway. Leave blank for OpenAI.
+                        </p>
+                        {baseUrlConfigured && (
+                          <label className="flex items-center gap-1.5 text-[10px] text-muted-foreground">
+                            <input
+                              type="checkbox"
+                              checked={clearBaseUrl}
+                              onChange={(e) => {
+                                setClearBaseUrl(e.target.checked);
+                                if (e.target.checked) setBaseUrl("");
+                              }}
+                              className="h-3 w-3 accent-current"
+                            />
+                            Clear saved endpoint override
+                          </label>
+                        )}
+                        {envVar && envConfigured && endpointChanged && (
+                          <button
+                            type="button"
+                            onClick={handleSave}
+                            disabled={saving}
+                            className="rounded bg-accent px-2.5 py-1 text-[10px] font-medium text-foreground hover:bg-accent/80 disabled:opacity-40"
+                          >
+                            {saving ? (
+                              <IconLoader2 size={10} className="animate-spin" />
+                            ) : saved ? (
+                              <IconCheck size={10} />
+                            ) : (
+                              "Save endpoint"
+                            )}
+                          </button>
+                        )}
+                      </div>
+                    )}
+                  </div>
+                )}
+
                 {envVar && envConfigured ? (
                   <div className="flex items-center gap-1.5 text-[10px] text-green-500">
                     <IconCheck size={10} />
@@ -939,7 +1054,7 @@ function LLMSectionInner({
                     />
                     <button
                       onClick={handleSave}
-                      disabled={!apiKey.trim() || saving}
+                      disabled={!providerSettingsChanged || saving}
                       className="rounded bg-accent px-2 py-1 text-[10px] font-medium text-foreground hover:bg-accent/80 disabled:opacity-40"
                     >
                       {saving ? (

package/corpus/core/src/scripts/agent-engines/manage-agent-engine.ts

@@ -56,6 +56,11 @@ export const tool: ActionTool = {
         description:
           "Model ID (e.g. 'gpt-5.5', 'claude-sonnet-4-6', 'gemini-3-1-pro'). Required for \"set-app-default\"; optional for \"set\" and \"test\" where it defaults to the engine's default model.",
       },
+      baseUrl: {
+        type: "string",
+        description:
+          'Optional OpenAI-compatible endpoint URL for action="test" with engine="ai-sdk:openai". Saved endpoint settings are used when omitted.',
+      },
       appId: {
         type: "string",
         description:

package/corpus/core/src/scripts/agent-engines/set-agent-engine.ts

@@ -6,6 +6,7 @@ import {
   listAgentEngines,
   getAgentEngineEntry,
   isAgentEnginePackageInstalled,
+  isStoredEngineUsableForRequest,
   normalizeModelForEngine,
   registerBuiltinEngines,
 } from "../../agent/engine/index.js";
@@ -67,9 +68,13 @@ export async function run(args: Record<string, string>): Promise<string> {
     entry.supportedModels.length === 0 ||
     entry.supportedModels.includes(resolvedModel);
 
-  const missingEnvVars = entry.requiredEnvVars.filter((v) => !process.env[v]);
-  if (missingEnvVars.length > 0) {
-    return `Warning: Engine "${engineName}" requires the following environment variables which are not set: ${missingEnvVars.join(", ")}. The engine will fail at runtime without them.`;
+  const usable = await isStoredEngineUsableForRequest(
+    { engine: engineName },
+    entry,
+  );
+  if (!usable) {
+    const missingEnvVars = entry.requiredEnvVars.join(", ");
+    return `Warning: Engine "${engineName}" requires the following credentials which are not configured for this request: ${missingEnvVars}. The engine will fail at runtime without them.`;
   }
 
   await putSetting("agent-engine", {

package/corpus/core/src/scripts/agent-engines/test-agent-engine.ts

@@ -5,8 +5,18 @@
 import {
   getAgentEngineEntry,
   registerBuiltinEngines,
+  type AgentEngineEntry,
 } from "../../agent/engine/index.js";
+import {
+  normalizeOpenAiBaseUrl,
+  OPENAI_BASE_URL_ENV_VAR,
+} from "../../agent/engine/openai-compatible-endpoint.js";
 import type { ActionTool } from "../../agent/types.js";
+import {
+  canUseDeployCredentialFallbackForRequest,
+  readDeployCredentialEnv,
+  resolveSecret,
+} from "../../server/credential-provider.js";
 
 export const tool: ActionTool = {
   description:
@@ -24,11 +34,54 @@ export const tool: ActionTool = {
         description:
           "Model to use for the test. Defaults to the engine's default model.",
       },
+      baseUrl: {
+        type: "string",
+        description:
+          'Optional OpenAI-compatible endpoint URL to test with "ai-sdk:openai". Uses the saved endpoint when omitted.',
+      },
     },
     required: [],
   },
 };
 
+async function resolveAgentEngineSecret(
+  key: string,
+): Promise<string | undefined> {
+  try {
+    const value = await resolveSecret(key);
+    if (value) return value;
+  } catch {
+    // Fall through to deploy env when this request is allowed to use it.
+  }
+  return canUseDeployCredentialFallbackForRequest()
+    ? readDeployCredentialEnv(key)
+    : undefined;
+}
+
+async function createEngineConfig(
+  entry: AgentEngineEntry,
+  args: Record<string, string>,
+): Promise<Record<string, unknown>> {
+  const config: Record<string, unknown> = {
+    apiKey:
+      entry.requiredEnvVars.length > 0
+        ? await resolveAgentEngineSecret(entry.requiredEnvVars[0])
+        : undefined,
+    allowEnvFallback: canUseDeployCredentialFallbackForRequest(),
+  };
+
+  if (entry.name === "ai-sdk:openai") {
+    const rawBaseUrl = args.baseUrl?.trim()
+      ? args.baseUrl
+      : await resolveAgentEngineSecret(OPENAI_BASE_URL_ENV_VAR);
+    if (rawBaseUrl) {
+      config.baseUrl = normalizeOpenAiBaseUrl(rawBaseUrl);
+    }
+  }
+
+  return config;
+}
+
 export async function run(args: Record<string, string>): Promise<string> {
   registerBuiltinEngines();
 
@@ -44,12 +97,7 @@ export async function run(args: Record<string, string>): Promise<string> {
   const model = args.model ?? entry.defaultModel;
 
   try {
-    const engine = entry.create({
-      apiKey:
-        entry.requiredEnvVars.length > 0
-          ? process.env[entry.requiredEnvVars[0]]
-          : undefined,
-    });
+    const engine = entry.create(await createEngineConfig(entry, args));
 
     const start = Date.now();
     const controller = new AbortController();

package/corpus/core/src/server/agent-engine-api-key-route.ts

@@ -5,9 +5,13 @@ import {
   type H3Event,
 } from "h3";
 
-import { PROVIDER_ENV_META } from "../agent/engine/provider-env-vars.js";
+import { normalizeOpenAiBaseUrl } from "../agent/engine/openai-compatible-endpoint.js";
+import {
+  OPENAI_BASE_URL_ENV_VAR,
+  PROVIDER_ENV_META,
+} from "../agent/engine/provider-env-vars.js";
 import { getOrgContext } from "../org/context.js";
-import { writeAppSecret } from "../secrets/storage.js";
+import { deleteAppSecret, writeAppSecret } from "../secrets/storage.js";
 import { getSession } from "./auth.js";
 import { readBody } from "./h3-helpers.js";
 
@@ -30,7 +34,9 @@ export function normalizeAgentEngineApiKeyPayload(body: unknown):
   | {
       ok: true;
       key: string;
-      value: string;
+      value?: string;
+      baseUrl?: string;
+      clearBaseUrl: boolean;
       scope: AgentEngineApiKeyScope;
     }
   | { ok: false; statusCode: number; error: string } {
@@ -40,6 +46,9 @@ export function normalizeAgentEngineApiKeyPayload(body: unknown):
     provider?: unknown;
     value?: unknown;
     apiKey?: unknown;
+    baseUrl?: unknown;
+    endpointUrl?: unknown;
+    clearBaseUrl?: unknown;
     scope?: unknown;
   };
 
@@ -63,8 +72,48 @@ export function normalizeAgentEngineApiKeyPayload(body: unknown):
       : typeof raw.apiKey === "string"
         ? raw.apiKey.trim()
         : "";
-  if (!value) {
-    return { ok: false, statusCode: 400, error: "value is required" };
+
+  const rawBaseUrl =
+    typeof raw.baseUrl === "string"
+      ? raw.baseUrl
+      : typeof raw.endpointUrl === "string"
+        ? raw.endpointUrl
+        : "";
+  let baseUrl: string | undefined;
+  if (rawBaseUrl.trim()) {
+    if (key !== PROVIDER_TO_ENV_VAR.get("openai")) {
+      return {
+        ok: false,
+        statusCode: 400,
+        error: "Endpoint URL is only supported for OpenAI.",
+      };
+    }
+    try {
+      baseUrl = normalizeOpenAiBaseUrl(rawBaseUrl);
+    } catch (err) {
+      return {
+        ok: false,
+        statusCode: 400,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  const clearBaseUrl = raw.clearBaseUrl === true && baseUrl == null;
+  if (clearBaseUrl && key !== PROVIDER_TO_ENV_VAR.get("openai")) {
+    return {
+      ok: false,
+      statusCode: 400,
+      error: "Endpoint URL is only supported for OpenAI.",
+    };
+  }
+
+  if (!value && !baseUrl && !clearBaseUrl) {
+    return {
+      ok: false,
+      statusCode: 400,
+      error: "value or baseUrl is required",
+    };
   }
 
   if (raw.scope != null && raw.scope !== "user" && raw.scope !== "org") {
@@ -78,7 +127,9 @@ export function normalizeAgentEngineApiKeyPayload(body: unknown):
   return {
     ok: true,
     key,
-    value,
+    ...(value ? { value } : {}),
+    ...(baseUrl ? { baseUrl } : {}),
+    clearBaseUrl,
     scope: raw.scope === "org" ? "org" : "user",
   };
 }
@@ -144,16 +195,36 @@ export function createAgentEngineApiKeyHandler() {
       return { error: resolved.error };
     }
 
-    await writeAppSecret({
-      key: payload.key,
-      value: payload.value,
-      scope: resolved.target.scope,
-      scopeId: resolved.target.scopeId,
-    });
+    if (payload.value) {
+      await writeAppSecret({
+        key: payload.key,
+        value: payload.value,
+        scope: resolved.target.scope,
+        scopeId: resolved.target.scopeId,
+      });
+    }
+
+    if (payload.baseUrl) {
+      await writeAppSecret({
+        key: OPENAI_BASE_URL_ENV_VAR,
+        value: payload.baseUrl,
+        scope: resolved.target.scope,
+        scopeId: resolved.target.scopeId,
+      });
+    } else if (payload.clearBaseUrl) {
+      await deleteAppSecret({
+        key: OPENAI_BASE_URL_ENV_VAR,
+        scope: resolved.target.scope,
+        scopeId: resolved.target.scopeId,
+      });
+    }
 
     return {
       ok: true,
       key: payload.key,
+      ...(payload.baseUrl || payload.clearBaseUrl
+        ? { baseUrlKey: OPENAI_BASE_URL_ENV_VAR }
+        : {}),
       scope: resolved.target.scope,
     };
   });

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

@@ -14,7 +14,10 @@ import { readMultipartFormData } from "h3";
 
 import { DEFAULT_MODEL } from "../agent/default-model.js";
 import { registerBuiltinEngines } from "../agent/engine/builtin.js";
-import { PROVIDER_ENV_META } from "../agent/engine/provider-env-vars.js";
+import {
+  OPENAI_BASE_URL_ENV_VAR,
+  PROVIDER_ENV_META,
+} from "../agent/engine/provider-env-vars.js";
 import {
   isAgentEngineSettingConfigured,
   getAgentEngineEntry,
@@ -123,6 +126,7 @@ import {
 import type { EnvKeyConfig } from "./create-server.js";
 import {
   canUseDeployCredentialFallbackForRequest,
+  readDeployCredentialEnv,
   resolveSecret,
 } from "./credential-provider.js";
 import { createEmbedStartRouteHandler } from "./embed-route.js";
@@ -2311,6 +2315,20 @@ export function createCoreRoutesPlugin(
                 /* org module not present in this template */
               }
             }
+            const openAiBaseUrlConfigured = await runWithRequestContext(
+              { userEmail, orgId },
+              async () => {
+                try {
+                  if (await resolveSecret(OPENAI_BASE_URL_ENV_VAR)) return true;
+                } catch {
+                  /* fall through to deployment env when allowed */
+                }
+                return (
+                  canUseDeployCredentialFallbackForRequest() &&
+                  !!readDeployCredentialEnv(OPENAI_BASE_URL_ENV_VAR)
+                );
+              },
+            );
             const stored = (await getSetting("agent-engine")) as {
               engine?: string;
               model?: string;
@@ -2323,6 +2341,7 @@ export function createCoreRoutesPlugin(
                 engine,
                 model: stored?.model ?? entry?.defaultModel ?? DEFAULT_MODEL,
                 source: "settings" as const,
+                openAiBaseUrlConfigured,
               };
             }
             const envEntry = process.env.AGENT_ENGINE
@@ -2338,7 +2357,7 @@ export function createCoreRoutesPlugin(
                   ),
               );
               if (!envUsable) {
-                return { configured: false };
+                return { configured: false, openAiBaseUrlConfigured };
               }
               return {
                 configured: true,
@@ -2346,6 +2365,7 @@ export function createCoreRoutesPlugin(
                 model: envEntry.defaultModel ?? DEFAULT_MODEL,
                 source: "env" as const,
                 envVar: "AGENT_ENGINE",
+                openAiBaseUrlConfigured,
               };
             }
             // Per-user app_secrets — a user who connected Builder (or pasted
@@ -2363,6 +2383,7 @@ export function createCoreRoutesPlugin(
                 model: detectedFromUser.defaultModel ?? DEFAULT_MODEL,
                 source: "app_secrets" as const,
                 envVar: detectedFromUser.requiredEnvVars[0],
+                openAiBaseUrlConfigured,
               };
             }
             if (stored && typeof stored.engine === "string") {
@@ -2379,6 +2400,7 @@ export function createCoreRoutesPlugin(
                   model: stored.model ?? entry.defaultModel ?? DEFAULT_MODEL,
                   source: "env" as const,
                   envVar: entry.requiredEnvVars[0],
+                  openAiBaseUrlConfigured,
                 };
               }
             }
@@ -2389,6 +2411,7 @@ export function createCoreRoutesPlugin(
                 model: detectedFromUser.defaultModel ?? DEFAULT_MODEL,
                 source: "app_secrets" as const,
                 envVar: detectedFromUser.requiredEnvVars[0],
+                openAiBaseUrlConfigured,
               };
             }
             const canUseDeployEnv = await runWithRequestContext(
@@ -2403,6 +2426,7 @@ export function createCoreRoutesPlugin(
                 model: detected.defaultModel ?? DEFAULT_MODEL,
                 source: "env" as const,
                 envVar: detected.requiredEnvVars[0],
+                openAiBaseUrlConfigured,
               };
             }
           } catch {}

package/corpus/core/src/styles/blocks.css

@@ -1231,6 +1231,7 @@
   --wf-muted: var(--plan-muted, hsl(var(--muted-foreground)));
   --wf-line: var(--plan-line, hsl(var(--border)));
   --wf-sketch: var(--plan-muted-line, hsl(var(--border)));
+  --wf-diagram-line: var(--wf-line);
   --wf-paper: var(--plan-document, hsl(var(--background)));
   --wf-card: var(--plan-block, hsl(var(--card)));
   --wf-accent: hsl(var(--ring));
@@ -1256,6 +1257,10 @@
   line-height: 1.4;
 }
 
+.plan-diagram-frame[data-theme="dark"] {
+  --wf-diagram-line: color-mix(in srgb, var(--wf-sketch) 72%, var(--wf-line));
+}
+
 .plan-diagram-frame[data-style="sketchy"] {
   --wf-font: var(--wf-font-hand);
   line-height: 1.32;
@@ -1275,9 +1280,7 @@
 }
 
 .plan-diagram-frame-content
-  > :is(.diagram-panel, .diagram-card, .diagram-box):not([data-rough]):not(
-    [data-diagram-frame]
-  ) {
+  > .diagram-panel:not([data-rough]):not([data-diagram-frame]) {
   --rough-skip: 1;
   background: transparent;
   border-color: transparent;
@@ -1318,7 +1321,8 @@
 
 .plan-diagram-frame
   :is(.diagram-panel, .diagram-card, .diagram-node, .diagram-box) {
-  border: 1.25px solid var(--wf-line);
+  --rough-stroke: var(--wf-diagram-line);
+  border: 1.25px solid var(--wf-diagram-line);
   border-radius: var(--wf-radius);
   background: var(--wf-card);
 }
@@ -1333,7 +1337,8 @@
     [class*="panel"],
     [class*="box"]
   ) {
-  border-color: var(--wf-line) !important;
+  --rough-stroke: var(--wf-diagram-line);
+  border-color: var(--wf-diagram-line) !important;
   background: var(--wf-card) !important;
   color: var(--wf-ink) !important;
 }
@@ -1366,7 +1371,8 @@
 
 .plan-diagram-frame
   :is(.diagram-pill, [class*="pill"], [class*="badge"], [class*="chip"]) {
-  border-color: var(--wf-line) !important;
+  --rough-stroke: var(--wf-diagram-line);
+  border-color: var(--wf-diagram-line) !important;
   background: var(--wf-paper) !important;
   color: var(--wf-ink) !important;
 }
@@ -1411,7 +1417,7 @@
    * variant used across the docs diagrams stays pill-shaped, not a full bar. */
   width: fit-content;
   max-width: 100%;
-  border: 1px solid var(--wf-line);
+  border: 1px solid var(--wf-diagram-line);
   border-radius: 999px;
   padding: 3px 11px;
   color: var(--wf-ink);
@@ -1453,6 +1459,16 @@
     [data-rough],
     hr
   ) {
+  border-color: color-mix(
+    in srgb,
+    var(--wf-diagram-line) 54%,
+    transparent
+  ) !important;
+}
+
+.plan-diagram-frame[data-rough-ready]
+  .plan-diagram-frame-content
+  > .diagram-panel:not([data-rough]):not([data-diagram-frame]) {
   border-color: transparent !important;
 }
 

package/corpus/templates/analytics/actions/list-session-recordings.ts

@@ -26,7 +26,7 @@ export default defineAction({
     app: z.string().optional().describe("Optional app filter"),
     template: z.string().optional().describe("Optional template filter"),
     sessionId: z.string().optional().describe("Optional analytics session id"),
-    userId: z.string().optional().describe("Optional signed-in user id"),
+    userId: z.string().optional().describe("Optional signed-in user email"),
     anonymousId: z.string().optional().describe("Optional anonymous user id"),
     path: z.string().optional().describe("Optional exact path filter"),
     from: z