@agent-native/core 0.79.20 → 0.79.22

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2031
-- template files: 4416
+- core files: 2032
+- template files: 4434

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @agent-native/core
 
+## 0.79.22
+
+### Patch Changes
+
+- cdf41db: Require signed-in email identity for browser session replay by default across templates and send replay timing/event-count metadata with each upload. Apps that intentionally record anonymous replay sessions can opt out with `sessionReplay.requireSignedInUser: false` or `VITE_AGENT_NATIVE_SESSION_REPLAY_REQUIRE_AUTH=false`.
+- cdf41db: Keep diagram primitive borders visible in sketchy Plan diagrams and stop the shared feedback button from sending synthetic anonymous Agent Native emails.
+- cdf41db: Add an advanced OpenAI-compatible endpoint URL setting for custom gateways like LiteLLM.
+- cdf41db: Default shared expandable code surfaces to 30 visible lines before the reader
+  expands them.
+
+## 0.79.21
+
+### Patch Changes
+
+- 3acd677: Clarify workspace Docker Compose deployment for self-hosted VPS installs.
+
 ## 0.79.20
 
 ### Patch Changes

package/corpus/core/docs/content/deployment.md

@@ -145,6 +145,139 @@ EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]
 ```
 
+### Self-hosted workspace with Docker Compose {#workspace-docker-compose}
+
+The Dockerfile above is for one standalone app. A workspace is not one Nitro
+server process today: each app still builds to its own `.output/` directory and
+runs its own Node/Nitro server. For a VPS, run one container per workspace app,
+point every app at the same Postgres database and shared production secrets, and
+put a reverse proxy in front that routes path prefixes (`/mail`, `/calendar`,
+...) to the matching app container.
+
+Build each app with the same base path that the proxy will use at runtime. The
+base path is a build-time input for the client bundle and a runtime input for
+the server:
+
+```bash maxLines=8
+APP_BASE_PATH=/mail VITE_APP_BASE_PATH=/mail npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+A reusable workspace Dockerfile can take the app name and path prefix as build
+arguments:
+
+```dockerfile maxLines=12
+FROM node:24-slim AS build
+WORKDIR /workspace
+RUN corepack enable
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages ./packages
+COPY apps ./apps
+ARG APP_NAME
+ARG APP_BASE_PATH
+ENV APP_BASE_PATH=$APP_BASE_PATH
+ENV VITE_APP_BASE_PATH=$APP_BASE_PATH
+RUN pnpm install --frozen-lockfile
+RUN pnpm --dir apps/$APP_NAME build
+
+FROM node:24-slim
+WORKDIR /app
+ARG APP_NAME
+ARG APP_BASE_PATH
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV APP_BASE_PATH=$APP_BASE_PATH
+COPY --from=build /workspace/apps/$APP_NAME/.output .output
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+Then compose Postgres, the app containers, and your proxy. This example uses
+Caddy because it can terminate HTTP locally or sit behind Cloudflare's SSL
+proxy, but the important part is the path-prefix routing:
+
+```yaml maxLines=30
+services:
+  postgres:
+    image: postgres:17
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: agent_native
+      POSTGRES_USER: agent_native
+      POSTGRES_PASSWORD: change-me
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  mail:
+    build:
+      context: .
+      dockerfile: Dockerfile.workspace-app
+      args:
+        APP_NAME: mail
+        APP_BASE_PATH: /mail
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgres://agent_native:change-me@postgres:5432/agent_native
+      BETTER_AUTH_URL: https://agents.example.com/mail
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      A2A_SECRET: ${A2A_SECRET}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+    depends_on:
+      - postgres
+
+  calendar:
+    build:
+      context: .
+      dockerfile: Dockerfile.workspace-app
+      args:
+        APP_NAME: calendar
+        APP_BASE_PATH: /calendar
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgres://agent_native:change-me@postgres:5432/agent_native
+      BETTER_AUTH_URL: https://agents.example.com/calendar
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      A2A_SECRET: ${A2A_SECRET}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+    depends_on:
+      - postgres
+
+  proxy:
+    image: caddy:2
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+    depends_on:
+      - mail
+      - calendar
+
+volumes:
+  postgres-data:
+```
+
+```caddyfile
+agents.example.com {
+  reverse_proxy /mail* mail:3000
+  reverse_proxy /calendar* calendar:3000
+}
+```
+
+Notes for this shape:
+
+- Keep `DATABASE_URL`, `BETTER_AUTH_SECRET`, `A2A_SECRET`, and other production
+  secrets identical across app containers when you want shared auth, shared
+  credentials, and cross-app A2A.
+- Set `BETTER_AUTH_URL` to the public URL for that app path. OAuth callback URLs
+  should use the same public URL.
+- Do not rely on the container filesystem for production data; use Postgres (or
+  another persistent SQL backend) for `DATABASE_URL`.
+- If Cloudflare terminates TLS in front of the VPS, configure Cloudflare to send
+  normal `X-Forwarded-Proto` / `X-Forwarded-Host` headers and route the public
+  host to the proxy container.
+
 ## Vercel {#vercel}
 
 ```ts

package/corpus/core/docs/content/faq.md

@@ -54,7 +54,7 @@ Yes. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS, Deno Dep
 
 ### What AI models does it support? {#what-models}
 
-Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, and any provider that speaks the OpenAI API shape (including local models via Ollama). You configure the model in settings; switching is a config change, not a code rewrite. The framework's heaviest tested path is Claude, so that's the default recommendation.
+Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, and any provider that speaks the OpenAI API shape. For OpenAI-compatible gateways like LiteLLM, choose OpenAI in Settings and add the gateway URL under Advanced. You configure the model in settings; switching is a config change, not a code rewrite. The framework's heaviest tested path is Claude, so that's the default recommendation.
 
 ### Do I need to know AI/ML? {#do-i-need-to-know-ai}
 

package/corpus/core/docs/content/multi-app-workspace.md

@@ -289,6 +289,8 @@ These settings only affect read-only page navigation. Framework tools, agent cha
 
 Prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && npx @agent-native/core@latest build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`. Cross-domain SSO between separately-deployed apps is handled by identity federation with Dispatch as the hub — see [Cross-App SSO](/docs/cross-app-sso); the unified single-origin deploy avoids needing it.
 
+For a self-hosted VPS or Docker Compose setup on one origin, build and run one container per app with its own path prefix (`APP_BASE_PATH=/mail`, `APP_BASE_PATH=/calendar`, ...), then route those prefixes through a reverse proxy. See [Deployment — Self-hosted workspace with Docker Compose](/docs/deployment#workspace-docker-compose) for the Dockerfile and compose example.
+
 ### Shared database, shared credentials
 
 Whatever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. If each app has its own database, the workspace pattern still works — you just lose that shared-state story.

package/corpus/core/docs/content/tracking.md

@@ -144,7 +144,6 @@ configureTracking({
   endpoint: "https://analytics.example.com/api/analytics/track",
   sessionReplay: {
     enabled: true,
-    requireSignedInUser: true,
     sampleRate: 0.1,
   },
   getDefaultProps: (_event, props) => ({
@@ -163,11 +162,12 @@ Agent Native template roots already call `configureTracking()`. Hosted template
 VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY=anpk_...
 VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT=https://analytics.example.com/api/analytics/track
 VITE_AGENT_NATIVE_SESSION_REPLAY_ENABLED=true
-VITE_AGENT_NATIVE_SESSION_REPLAY_REQUIRE_AUTH=true
 VITE_AGENT_NATIVE_SESSION_REPLAY_SAMPLE_RATE=0.1
 ```
 
-The browser helper also performs a best-effort, non-blocking read of the current Agent Native auth session. When `requireSignedInUser` or `VITE_AGENT_NATIVE_SESSION_REPLAY_REQUIRE_AUTH` is enabled, replay does not start unless the session resolves to a signed-in user. Signed-in replays include `userId`/`userEmail` plus `orgId`; if auth gating is disabled, anonymous recordings remain queryable by anonymous visitor, session, app/template, hostname, and path.
+The browser helper also performs a best-effort, non-blocking read of the current Agent Native auth session. Replay is signed-in-only by default: when `sessionReplay` is enabled, recording does not start unless the session resolves to a user email address. Signed-in replays include email-backed `userId`/`userEmail` plus `orgId`.
+
+Set `sessionReplay.requireSignedInUser: false` or `VITE_AGENT_NATIVE_SESSION_REPLAY_REQUIRE_AUTH=false` only for an intentional anonymous replay deployment. When auth gating is disabled, anonymous recordings remain queryable by anonymous visitor, session, app/template, hostname, and path.
 
 Session replay is sampled deterministically per browser session. A `sampleRate` of `0.1` records about 10% of eligible sessions; use `1` when the eligible population is intentionally small, such as logged-in-only dogfooding.
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.79.20",
+  "version": "0.79.22",
   "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/agent/engine/openai-compatible-endpoint.ts

@@ -0,0 +1,25 @@
+export const OPENAI_BASE_URL_ENV_VAR = "OPENAI_BASE_URL";
+
+export function normalizeOpenAiBaseUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error("Endpoint URL is required.");
+  }
+
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new Error("Endpoint URL must be a valid URL.");
+  }
+
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error("Endpoint URL must start with http:// or https://.");
+  }
+  if (url.username || url.password) {
+    throw new Error("Endpoint URL must not include credentials.");
+  }
+
+  url.hash = "";
+  return url.toString().replace(/\/+$/, "");
+}

package/corpus/core/src/agent/engine/provider-env-vars.ts

@@ -16,6 +16,8 @@ export interface ProviderEnvMeta {
   placeholder: string;
 }
 
+export { OPENAI_BASE_URL_ENV_VAR } from "./openai-compatible-endpoint.js";
+
 export const PROVIDER_ENV_META: Record<string, ProviderEnvMeta> = {
   anthropic: {
     envVar: "ANTHROPIC_API_KEY",

package/corpus/core/src/agent/engine/registry.ts

@@ -18,6 +18,10 @@ import {
 } from "../../server/credential-provider.js";
 import { getSetting } from "../../settings/store.js";
 import { getAgentAppModelDefaultForCurrentRequest } from "../app-model-defaults.js";
+import {
+  normalizeOpenAiBaseUrl,
+  OPENAI_BASE_URL_ENV_VAR,
+} from "./openai-compatible-endpoint.js";
 import type { AgentEngine, EngineCapabilities } from "./types.js";
 
 const require = createRequire(import.meta.url);
@@ -324,6 +328,39 @@ function engineCreateConfig(
   };
 }
 
+async function resolveOpenAiBaseUrl(): Promise<string | undefined> {
+  let raw: string | null | undefined = null;
+  try {
+    raw = await resolveSecret(OPENAI_BASE_URL_ENV_VAR);
+  } catch {
+    raw = null;
+  }
+
+  if (!raw && canUseDeployCredentialFallbackForRequest()) {
+    raw = readDeployCredentialEnv(OPENAI_BASE_URL_ENV_VAR);
+  }
+
+  return raw ? normalizeOpenAiBaseUrl(raw) : undefined;
+}
+
+async function engineCreateConfigForEntry(
+  entry: AgentEngineEntry,
+  apiKey: string | undefined,
+  extra?: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const safeExtra = { ...(extra ?? {}) };
+  if (entry.name === "ai-sdk:openai") {
+    if (typeof safeExtra.baseURL === "string" && safeExtra.baseUrl == null) {
+      safeExtra.baseUrl = normalizeOpenAiBaseUrl(safeExtra.baseURL);
+    }
+    if (safeExtra.baseUrl == null) {
+      const baseUrl = await resolveOpenAiBaseUrl();
+      if (baseUrl) safeExtra.baseUrl = baseUrl;
+    }
+  }
+  return engineCreateConfig(apiKey, safeExtra);
+}
+
 /**
  * True when the stored `agent-engine` row points at a registered engine
  * AND an API key for it is reachable via the engine's required env vars.
@@ -432,7 +469,9 @@ export async function resolveEngine(
         `[agent-engine] Unknown engine: "${name}". Registered: ${[..._registry.keys()].join(", ")}`,
       );
     assertAgentEnginePackageInstalled(entry);
-    return entry.create(engineCreateConfig(apiKey, engineConfig));
+    return entry.create(
+      await engineCreateConfigForEntry(entry, apiKey, engineConfig),
+    );
   }
 
   // 3. Explicit string name from options
@@ -443,7 +482,7 @@ export async function resolveEngine(
         `[agent-engine] Unknown engine: "${engineOption}". Registered: ${[..._registry.keys()].join(", ")}`,
       );
     assertAgentEnginePackageInstalled(entry);
-    return entry.create(engineCreateConfig(apiKey));
+    return entry.create(await engineCreateConfigForEntry(entry, apiKey));
   }
 
   // 4. Env var — explicit engine name override
@@ -452,7 +491,7 @@ export async function resolveEngine(
     const entry = _registry.get(envEngine);
     if (entry) {
       assertAgentEnginePackageInstalled(entry);
-      return entry.create(engineCreateConfig(apiKey));
+      return entry.create(await engineCreateConfigForEntry(entry, apiKey));
     }
   }
 
@@ -460,7 +499,7 @@ export async function resolveEngine(
   if (appDefault?.engine) {
     const entry = _registry.get(appDefault.engine);
     if (entry && (await isStoredEngineUsableForRequest(appDefault, entry))) {
-      return entry.create(engineCreateConfig(apiKey));
+      return entry.create(await engineCreateConfigForEntry(entry, apiKey));
     }
   }
 
@@ -477,7 +516,9 @@ export async function resolveEngine(
   // Builder connection wins over a stale deploy-level/provider key.
   const detectedFromUser = await detectEngineFromUserSecrets();
   if (detectedFromUser?.name === "builder") {
-    return detectedFromUser.create(engineCreateConfig(apiKey));
+    return detectedFromUser.create(
+      await engineCreateConfigForEntry(detectedFromUser, apiKey),
+    );
   }
 
   // 6. Settings store — only when the stored row's API key is reachable.
@@ -490,19 +531,22 @@ export async function resolveEngine(
   if (storedRaw && typeof storedEngine === "string") {
     const entry = _registry.get(storedEngine);
     if (entry && (await isStoredEngineUsableForRequest(storedRaw, entry))) {
-      return entry.create({
-        ...engineCreateConfig(
+      return entry.create(
+        await engineCreateConfigForEntry(
+          entry,
           apiKey,
           stripInlineApiKeyConfig(
             storedConfig as Record<string, unknown> | undefined,
           ),
         ),
-      });
+      );
     }
   }
 
   if (detectedFromUser) {
-    return detectedFromUser.create(engineCreateConfig(apiKey));
+    return detectedFromUser.create(
+      await engineCreateConfigForEntry(detectedFromUser, apiKey),
+    );
   }
 
   // 8. Auto-detect from any provider env var — so just dropping a key in
@@ -510,7 +554,9 @@ export async function resolveEngine(
   const detected = canUseDeployCredentialFallbackForRequest()
     ? detectEngineFromEnv()
     : null;
-  if (detected) return detected.create(engineCreateConfig(apiKey));
+  if (detected) {
+    return detected.create(await engineCreateConfigForEntry(detected, apiKey));
+  }
 
   // 9. Default: anthropic
   const anthropicEntry = _registry.get("anthropic");
@@ -519,7 +565,9 @@ export async function resolveEngine(
       "[agent-engine] Default Anthropic engine is not registered. Did builtin.ts fail to load?",
     );
   }
-  return anthropicEntry.create(engineCreateConfig(apiKey));
+  return anthropicEntry.create(
+    await engineCreateConfigForEntry(anthropicEntry, apiKey),
+  );
 }
 
 /**

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

@@ -20,6 +20,12 @@ import { cn } from "./utils.js";
 const DEFAULT_FEEDBACK_URL =
   "https://forms.agent-native.com/f/agent-native-feedback/_16ewV";
 
+function isSyntheticAgentNativeAnonymousEmail(
+  value: string | null | undefined,
+): boolean {
+  return /^anon-[^\s@]+@agent-native\.com$/i.test(value ?? "");
+}
+
 interface ParsedTarget {
   endpoint: string;
   slug: string;
@@ -342,7 +348,11 @@ export function FeedbackButton({
       try {
         const resolvedSchema = schema ?? (await loadSchema(target));
         if (!schema) setSchema(resolvedSchema);
-        const submitterEmail = session?.email;
+        const submitterEmail = isSyntheticAgentNativeAnonymousEmail(
+          session?.email,
+        )
+          ? null
+          : session?.email;
         const feedbackContext = getFeedbackClientContext({
           chatSessionId,
           storageKey: chatStorageKey,

package/corpus/core/src/client/agent-engine-key.ts

@@ -29,6 +29,32 @@ export interface SaveAgentEngineApiKeyOptions {
   scope?: "user" | "org";
 }
 
+export interface SaveAgentEngineProviderSettingsOptions {
+  provider?: AgentEngineProvider;
+  key?: string;
+  apiKey?: string;
+  baseUrl?: string;
+  clearBaseUrl?: boolean;
+  scope?: "user" | "org";
+}
+
+function resolveProviderEnvVar(
+  provider: AgentEngineProvider | undefined,
+  key: string | undefined,
+): string {
+  const envVar = key?.trim() || (provider ? PROVIDER_ENV_VAR[provider] : "");
+  if (!envVar) {
+    throw new Error("Choose an API key provider first.");
+  }
+  return envVar;
+}
+
+function dispatchConfiguredChanged(): void {
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(new CustomEvent(CONFIGURED_CHANGED_EVENT));
+  }
+}
+
 /**
  * Persist a provider API key for the current owner. Resolves on success.
  * Throws an Error with a readable message on failure. On success it also
@@ -41,20 +67,43 @@ export async function saveAgentEngineApiKey({
   apiKey,
   scope,
 }: SaveAgentEngineApiKeyOptions): Promise<void> {
-  const trimmed = apiKey.trim();
-  if (!trimmed) {
+  if (!apiKey.trim()) {
     throw new Error("Enter an API key first.");
   }
-  const envVar = key?.trim() || (provider ? PROVIDER_ENV_VAR[provider] : "");
-  if (!envVar) {
-    throw new Error("Choose an API key provider first.");
+  await saveAgentEngineProviderSettings({ provider, key, apiKey, scope });
+}
+
+/**
+ * Persist provider-specific settings for the current owner. This intentionally
+ * stays narrow: API keys for built-in BYOK providers, plus OpenAI's optional
+ * compatible endpoint URL. Values are stored server-side in scoped secrets.
+ */
+export async function saveAgentEngineProviderSettings({
+  provider,
+  key,
+  apiKey,
+  baseUrl,
+  clearBaseUrl,
+  scope,
+}: SaveAgentEngineProviderSettingsOptions): Promise<void> {
+  const trimmed = apiKey?.trim() ?? "";
+  const endpoint = baseUrl?.trim() ?? "";
+  if (!trimmed && !endpoint && !clearBaseUrl) {
+    throw new Error("Enter an API key or endpoint URL first.");
   }
+  const envVar = resolveProviderEnvVar(provider, key);
   const res = await fetch(
     agentNativePath("/_agent-native/agent-engine/api-key"),
     {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ key: envVar, value: trimmed, scope }),
+      body: JSON.stringify({
+        key: envVar,
+        ...(trimmed ? { value: trimmed } : {}),
+        ...(endpoint ? { baseUrl: endpoint } : {}),
+        ...(clearBaseUrl ? { clearBaseUrl: true } : {}),
+        scope,
+      }),
     },
   );
   if (!res.ok) {
@@ -66,10 +115,8 @@ export async function saveAgentEngineApiKey({
       message ??
         (res.status === 401
           ? "Sign in to save a key, or connect Builder instead."
-          : `Could not save the key (HTTP ${res.status}).`),
+          : `Could not save provider settings (HTTP ${res.status}).`),
     );
   }
-  if (typeof window !== "undefined") {
-    window.dispatchEvent(new CustomEvent(CONFIGURED_CHANGED_EVENT));
-  }
+  dispatchConfiguredChanged();
 }