@agent-native/core 0.207.0-nightly-20261011124220 → 0.207.0

package/dist/templates/chat/app/lib/chat-paths.ts

@@ -0,0 +1,479 @@
+import type { FilePart } from "@agent-native/agentkit";
+import {
+  COMPOSER_CONTEXT_MAX_BYTES,
+  COMPOSER_CONTEXT_MAX_ITEMS,
+  type PromptComposerSubmitOptions,
+  type Reference,
+} from "@agent-native/toolkit/composer";
+
+export const HOME_PATH = "/home";
+export const NEW_CHAT_PATH = "/chat";
+
+const FAILED_CHAT_HANDOFF_PREFIX = "agent-native.chat.failed-handoff:";
+const MAX_FAILED_HANDOFF_BYTES = COMPOSER_CONTEXT_MAX_BYTES * 2 + 32 * 1024;
+const MAX_HANDOFF_FIELD_LENGTH = 8 * 1024;
+const MAX_HANDOFF_ITEMS = 20;
+const INVALID_JSON_VALUE = Symbol("invalid-json-value");
+const HANDOFF_COMPOSER_OPTION_KEYS = new Set([
+  "mode",
+  "engine",
+  "model",
+  "effort",
+  "intent",
+  "steer",
+  "composerModeContext",
+  "references",
+  "uploadedAttachments",
+  "contextItems",
+]);
+
+export function chatThreadPath(threadId: string | null | undefined): string {
+  return threadId
+    ? `${NEW_CHAT_PATH}/${encodeURIComponent(threadId)}`
+    : NEW_CHAT_PATH;
+}
+
+export function isChatPathname(pathname: string): boolean {
+  return pathname === NEW_CHAT_PATH || pathname.startsWith(`${NEW_CHAT_PATH}/`);
+}
+
+export function threadIdFromPath(pathname: string): string | null {
+  const match = pathname.match(/^\/chat\/([^/]+)/);
+  if (!match) return null;
+  try {
+    const value = decodeURIComponent(match[1]).trim();
+    return value || null;
+    // coercion-ok: a malformed percent-encoding is not a thread id, so the path has no thread.
+  } catch {
+    return null;
+  }
+}
+
+export type ChatInitialComposerOptions = Omit<
+  PromptComposerSubmitOptions,
+  "onLocalSubmit" | "attachments"
+> & {
+  mode?: "act" | "plan";
+  references?: readonly Reference[];
+  uploadedAttachments?: readonly FilePart[];
+};
+
+/** Router state that carries a prompt typed elsewhere into the chat it opens. */
+export interface ChatRouteState {
+  initialMessage: string;
+  initialComposerOptions?: ChatInitialComposerOptions;
+}
+
+export interface FailedChatHandoffEnvelope {
+  text: string;
+  options: ChatInitialComposerOptions;
+}
+
+export type FailedChatHandoffReadResult =
+  | { status: "found"; handoff: FailedChatHandoffEnvelope }
+  | { status: "absent" }
+  | {
+      status: "invalid";
+      reason:
+        | "invalid-thread-id"
+        | "too-large"
+        | "invalid-json"
+        | "invalid-envelope";
+      cause?: unknown;
+    }
+  | { status: "unavailable"; cause: unknown };
+
+export type FailedChatHandoffWriteResult =
+  | { status: "stored" }
+  | {
+      status: "invalid";
+      reason: "invalid-thread-id" | "invalid-options" | "payload-too-large";
+    }
+  | { status: "unavailable"; cause: unknown };
+
+export type FailedChatHandoffClearResult =
+  | { status: "cleared" }
+  | { status: "absent" }
+  | { status: "unavailable"; cause: unknown };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeJsonValue(
+  value: unknown,
+  depth = 0,
+): unknown | typeof INVALID_JSON_VALUE {
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    return value.length <= MAX_HANDOFF_FIELD_LENGTH
+      ? value
+      : INVALID_JSON_VALUE;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : INVALID_JSON_VALUE;
+  }
+  if (depth >= 5) return INVALID_JSON_VALUE;
+  if (Array.isArray(value)) {
+    if (value.length > MAX_HANDOFF_ITEMS) return INVALID_JSON_VALUE;
+    const normalized = value.map((item) => normalizeJsonValue(item, depth + 1));
+    return normalized.some((item) => item === INVALID_JSON_VALUE)
+      ? INVALID_JSON_VALUE
+      : normalized;
+  }
+  if (!isRecord(value)) return INVALID_JSON_VALUE;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    return INVALID_JSON_VALUE;
+  }
+  const entries = Object.entries(value);
+  if (entries.length > MAX_HANDOFF_ITEMS) return INVALID_JSON_VALUE;
+  const normalized: Record<string, unknown> = {};
+  for (const [key, entry] of entries) {
+    if (key.length > 128) return INVALID_JSON_VALUE;
+    const normalizedEntry = normalizeJsonValue(entry, depth + 1);
+    if (normalizedEntry === INVALID_JSON_VALUE) return INVALID_JSON_VALUE;
+    normalized[key] = normalizedEntry;
+  }
+  return normalized;
+}
+
+function copyOptionalString(
+  source: Record<string, unknown>,
+  key: string,
+  target: Record<string, unknown>,
+  maxLength = MAX_HANDOFF_FIELD_LENGTH,
+): boolean {
+  if (!(key in source)) return true;
+  const value = source[key];
+  if (value === undefined || value === null) return true;
+  if (typeof value !== "string" || value.length > maxLength) return false;
+  target[key] = value;
+  return true;
+}
+
+function normalizeReference(value: unknown): Reference | null {
+  if (!isRecord(value)) return null;
+  const types = ["file", "skill", "mention", "agent", "custom-agent"];
+  if (!types.includes(String(value.type))) return null;
+  const result: Record<string, unknown> = { type: value.type };
+  for (const key of ["path", "name", "source"] as const) {
+    if (typeof value[key] !== "string" || value[key].length > 4096) {
+      return null;
+    }
+    result[key] = value[key];
+  }
+  for (const key of ["refType", "refId", "slotKey", "slotLabel"]) {
+    if (!copyOptionalString(value, key, result, 4096)) return null;
+  }
+  if (
+    "metadata" in value &&
+    value.metadata !== undefined &&
+    value.metadata !== null
+  ) {
+    const metadata = normalizeJsonValue(value.metadata);
+    if (!isRecord(metadata)) return null;
+    result.metadata = metadata;
+  }
+  return result as unknown as Reference;
+}
+
+function normalizeFilePart(value: unknown): FilePart | null {
+  if (!isRecord(value) || value.type !== "file") return null;
+  if (typeof value.name !== "string" || value.name.length > 1024) return null;
+  const result: Record<string, unknown> = { type: "file", name: value.name };
+  if (!copyOptionalString(value, "mediaType", result, 512)) return null;
+  if (!copyOptionalString(value, "fileId", result, 1024)) return null;
+  if (!copyOptionalString(value, "url", result, 4096)) return null;
+  if (typeof result.url === "string" && /^\s*data:/i.test(result.url)) {
+    return null;
+  }
+  if ("omitted" in value) {
+    if (value.omitted !== "inline-bytes" && value.omitted !== "unsafe-url") {
+      return null;
+    }
+    result.omitted = value.omitted;
+  }
+  return result as unknown as FilePart;
+}
+
+function normalizeContextItems(
+  value: unknown,
+): NonNullable<ChatInitialComposerOptions["contextItems"]> | null {
+  if (!Array.isArray(value) || value.length > COMPOSER_CONTEXT_MAX_ITEMS) {
+    return null;
+  }
+  const result: NonNullable<
+    ChatInitialComposerOptions["contextItems"]
+  >[number][] = [];
+  for (const item of value) {
+    if (!isRecord(item)) return null;
+    const normalized: Record<string, unknown> = {};
+    for (const key of ["key", "title", "context"] as const) {
+      if (typeof item[key] !== "string") return null;
+      normalized[key] = item[key];
+    }
+    for (const key of ["contextNamespace", "targetThreadId"]) {
+      if (!copyOptionalString(item, key, normalized, 4096)) return null;
+    }
+    result.push(
+      normalized as NonNullable<
+        ChatInitialComposerOptions["contextItems"]
+      >[number],
+    );
+  }
+  if (
+    new TextEncoder().encode(JSON.stringify(result)).byteLength >
+    COMPOSER_CONTEXT_MAX_BYTES
+  ) {
+    return null;
+  }
+  return result;
+}
+
+function normalizeComposerOptions(
+  value: unknown,
+): ChatInitialComposerOptions | null {
+  if (!isRecord(value)) return null;
+  if (
+    Object.keys(value).some((key) => !HANDOFF_COMPOSER_OPTION_KEYS.has(key))
+  ) {
+    return null;
+  }
+  if ("mode" in value && value.mode !== "act" && value.mode !== "plan") {
+    return null;
+  }
+  const result: Record<string, unknown> = {
+    mode: value.mode === "plan" ? "plan" : "act",
+  };
+  for (const key of ["engine", "model"] as const) {
+    if (!copyOptionalString(value, key, result, 512)) return null;
+  }
+  if ("effort" in value) {
+    if (
+      ![
+        "auto",
+        "none",
+        "minimal",
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+      ].includes(String(value.effort))
+    ) {
+      return null;
+    }
+    result.effort = value.effort;
+  }
+  if ("intent" in value) {
+    if (value.intent !== "immediate" && value.intent !== "queued") return null;
+    result.intent = value.intent;
+  }
+  if ("steer" in value) {
+    if (typeof value.steer !== "boolean") return null;
+    result.steer = value.steer;
+  }
+  if ("composerModeContext" in value) {
+    if (!copyOptionalString(value, "composerModeContext", result, 16 * 1024)) {
+      return null;
+    }
+  }
+  if ("references" in value) {
+    if (
+      !Array.isArray(value.references) ||
+      value.references.length > MAX_HANDOFF_ITEMS
+    ) {
+      return null;
+    }
+    const references = value.references.map(normalizeReference);
+    if (references.some((reference) => !reference)) return null;
+    result.references = references;
+  }
+  if ("uploadedAttachments" in value) {
+    if (
+      !Array.isArray(value.uploadedAttachments) ||
+      value.uploadedAttachments.length > MAX_HANDOFF_ITEMS
+    ) {
+      return null;
+    }
+    const attachments = value.uploadedAttachments.map(normalizeFilePart);
+    if (attachments.some((attachment) => !attachment)) return null;
+    result.uploadedAttachments = attachments;
+  }
+  if ("contextItems" in value) {
+    const contextItems = normalizeContextItems(value.contextItems);
+    if (!contextItems) return null;
+    result.contextItems = contextItems;
+  }
+  return result as ChatInitialComposerOptions;
+}
+
+function failedChatHandoffKey(threadId: string): string {
+  return `${FAILED_CHAT_HANDOFF_PREFIX}${encodeURIComponent(threadId)}`;
+}
+
+function clearFailedChatHandoffMarker(threadId: string): string {
+  return JSON.stringify({ version: 1, threadId, status: "cleared" });
+}
+
+function replaceFailedChatHandoffWithMarker(
+  threadId: string,
+): { status: "stored" } | { status: "unavailable"; cause: unknown } {
+  try {
+    window.sessionStorage.setItem(
+      failedChatHandoffKey(threadId),
+      clearFailedChatHandoffMarker(threadId),
+    );
+    return { status: "stored" };
+  } catch (cause) {
+    return { status: "unavailable", cause };
+  }
+}
+
+function invalidateExistingFailedChatHandoff(threadId: string): void {
+  if (typeof window === "undefined") return;
+  clearFailedChatHandoff(threadId);
+}
+
+/** Persist a bounded, JSON-safe Home-to-Chat submit until retry is accepted. */
+export function writeFailedChatHandoff(
+  threadId: string,
+  text: string,
+  options: ChatInitialComposerOptions,
+): FailedChatHandoffWriteResult {
+  if (typeof window === "undefined") {
+    return {
+      status: "unavailable",
+      cause: new Error("Chat handoff storage is only available in a browser"),
+    };
+  }
+  if (!threadId.trim() || threadId.length > 512) {
+    return { status: "invalid", reason: "invalid-thread-id" };
+  }
+  const normalizedOptions = normalizeComposerOptions(options);
+  if (!normalizedOptions) {
+    invalidateExistingFailedChatHandoff(threadId);
+    return { status: "invalid", reason: "invalid-options" };
+  }
+  const serialized = JSON.stringify({
+    version: 1,
+    threadId,
+    text,
+    options: normalizedOptions,
+  });
+  if (
+    new TextEncoder().encode(serialized).byteLength > MAX_FAILED_HANDOFF_BYTES
+  ) {
+    invalidateExistingFailedChatHandoff(threadId);
+    return { status: "invalid", reason: "payload-too-large" };
+  }
+  try {
+    window.sessionStorage.setItem(failedChatHandoffKey(threadId), serialized);
+    return { status: "stored" };
+  } catch (cause) {
+    invalidateExistingFailedChatHandoff(threadId);
+    return { status: "unavailable", cause };
+  }
+}
+
+export function readFailedChatHandoff(
+  threadId: string,
+): FailedChatHandoffReadResult {
+  if (typeof window === "undefined") return { status: "absent" };
+  if (!threadId.trim()) {
+    return { status: "invalid", reason: "invalid-thread-id" };
+  }
+  try {
+    const serialized = window.sessionStorage.getItem(
+      failedChatHandoffKey(threadId),
+    );
+    if (serialized === null) return { status: "absent" };
+    if (
+      new TextEncoder().encode(serialized).byteLength > MAX_FAILED_HANDOFF_BYTES
+    ) {
+      return { status: "invalid", reason: "too-large" };
+    }
+    let envelope: unknown;
+    try {
+      envelope = JSON.parse(serialized);
+    } catch (cause) {
+      return { status: "invalid", reason: "invalid-json", cause };
+    }
+    if (!isRecord(envelope) || envelope.version !== 1) {
+      return { status: "invalid", reason: "invalid-envelope" };
+    }
+    if (envelope.status === "cleared" && envelope.threadId === threadId) {
+      return { status: "absent" };
+    }
+    if (envelope.threadId !== threadId || typeof envelope.text !== "string") {
+      return { status: "invalid", reason: "invalid-envelope" };
+    }
+    const options = normalizeComposerOptions(envelope.options);
+    if (!options) return { status: "invalid", reason: "invalid-envelope" };
+    return { status: "found", handoff: { text: envelope.text, options } };
+  } catch (cause) {
+    return { status: "unavailable", cause };
+  }
+}
+
+export function clearFailedChatHandoff(
+  threadId: string,
+): FailedChatHandoffClearResult {
+  if (typeof window === "undefined") {
+    return {
+      status: "unavailable",
+      cause: new Error("Chat handoff storage is only available in a browser"),
+    };
+  }
+  if (!threadId.trim()) return { status: "absent" };
+  const key = failedChatHandoffKey(threadId);
+  try {
+    if (window.sessionStorage.getItem(key) === null) {
+      return { status: "absent" };
+    }
+  } catch (cause) {
+    const marker = replaceFailedChatHandoffWithMarker(threadId);
+    if (marker.status === "stored") {
+      return { status: "cleared" };
+    }
+    try {
+      window.sessionStorage.removeItem(key);
+      return { status: "cleared" };
+    } catch (removeCause) {
+      return { status: "unavailable", cause: removeCause ?? cause };
+    }
+  }
+  try {
+    window.sessionStorage.removeItem(key);
+    return { status: "cleared" };
+  } catch (cause) {
+    const marker = replaceFailedChatHandoffWithMarker(threadId);
+    if (marker.status === "stored") {
+      return { status: "cleared" };
+    }
+    return { status: "unavailable", cause };
+  }
+}
+
+export function initialMessageFromState(state: unknown): string | null {
+  if (!state || typeof state !== "object") return null;
+  const message = (state as Partial<ChatRouteState>).initialMessage;
+  return typeof message === "string" && message.trim() ? message : null;
+}
+
+export function initialComposerOptionsFromState(
+  state: unknown,
+): InitialComposerOptionsReadResult {
+  if (!isRecord(state) || !("initialComposerOptions" in state)) {
+    return { status: "absent" };
+  }
+  if (state.initialComposerOptions === undefined) return { status: "absent" };
+  const options = normalizeComposerOptions(state.initialComposerOptions);
+  return options ? { status: "valid", options } : { status: "invalid" };
+}
+
+export type InitialComposerOptionsReadResult =
+  | { status: "absent" }
+  | { status: "valid"; options: ChatInitialComposerOptions }
+  | { status: "invalid" };

package/dist/templates/chat/app/root.tsx

@@ -26,6 +26,12 @@ import { Layout as AppLayout } from "@/components/layout/Layout";
 import { AppToolkitProvider } from "@/components/ui/toolkit-provider";
 import { useNavigationState } from "@/hooks/use-navigation-state";
 import { APP_TITLE } from "@/lib/app-config";
+import {
+  HOME_PATH,
+  isChatPathname,
+  NEW_CHAT_PATH,
+  threadIdFromPath,
+} from "@/lib/chat-paths";
 import { TAB_ID } from "@/lib/tab-id";
 
 import { i18nCatalog } from "./i18n";
@@ -115,7 +121,7 @@ function AppContent() {
   const navigate = useNavigate();
   const t = useT();
   const location = useLocation();
-  const isChatThread = location.pathname.startsWith("/chat/");
+  const isChatThread = threadIdFromPath(location.pathname) !== null;
   useCommandMenuShortcut(useCallback(() => setCmdkOpen(true), []));
   return (
     <>
@@ -134,8 +140,13 @@ function AppContent() {
               {t("chat.newChat")}
             </CommandMenu.Item>
           ) : null}
-          {!isChatThread && location.pathname !== "/home" ? (
-            <CommandMenu.Item onSelect={() => navigate("/home")}>
+          {location.pathname !== HOME_PATH ? (
+            <CommandMenu.Item onSelect={() => navigate(HOME_PATH)}>
+              {t("navigation.home")}
+            </CommandMenu.Item>
+          ) : null}
+          {!isChatPathname(location.pathname) ? (
+            <CommandMenu.Item onSelect={() => navigate(NEW_CHAT_PATH)}>
               {t("navigation.chat")}
             </CommandMenu.Item>
           ) : null}

package/dist/templates/chat/app/routes/chat._index.tsx

@@ -0,0 +1,5 @@
+import ChatHomeRedirect from "@/components/chat/ChatHomeRedirect";
+
+export { meta } from "./home";
+
+export default ChatHomeRedirect;

package/dist/templates/chat/app/routes/home.tsx

@@ -1,9 +1,5 @@
-import { appPath } from "@agent-native/core/client/api-path";
-import { markAgentChatHomeHandoff } from "@agent-native/toolkit/app/chat/agentkit-chat/rail";
-import { useEffect, useRef, useState } from "react";
-
+import HomePage from "@/components/home/HomePage";
 import { APP_TITLE } from "@/lib/app-config";
-import { getChatHomeThreadId } from "@/lib/chat-home-thread";
 
 const SEO_TITLE = `${APP_TITLE} - Open Source AI app starter with actions`;
 const SEO_DESCRIPTION =
@@ -24,21 +20,6 @@ export function meta() {
   ];
 }
 
-export default function ChatRoute() {
-  const [threadId] = useState(getChatHomeThreadId);
-  const handoffStartedRef = useRef(false);
-
-  useEffect(() => {
-    if (handoffStartedRef.current) return;
-    handoffStartedRef.current = true;
-    markAgentChatHomeHandoff("chat");
-    try {
-      window.location.replace(appPath(`/chat/${encodeURIComponent(threadId)}`));
-    } catch (error) {
-      handoffStartedRef.current = false;
-      throw error;
-    }
-  }, [threadId]);
-
-  return null;
+export default function HomeRoute() {
+  return <HomePage />;
 }

package/dist/templates/chat/changelog/2026-10-10-home-handoff-recovery-capacity.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-10-10
+---
+
+Large prompts with full context remain available to retry when sending fails.

package/dist/templates/default/.agents/skills/secrets/SKILL.md

@@ -25,8 +25,12 @@ never copy a value into app code or client-visible state.
 3. If the app truly needs its own API key, register it with the shared secrets
    surface. Do not build a parallel key form or storage table.
 4. Use deployment configuration only for a secret owned by the deployed app,
-   such as a webhook verification secret. A deployment key must not stand in
-   for a user's or customer's provider credential.
+   such as a webhook verification secret. LLM inference keys are an app-owned
+   exception: self-hosted apps may use provider keys from deployment env as a
+   shared fallback, while scoped user or organization keys take precedence.
+   Hosted-workspace deployments backed by a shared database must not share
+   those env keys across apps or tenants. This exception does not authorize
+   using env credentials to access user-owned provider data.
 
 ## Register an app-local API key
 

package/dist/templates/headless/.agents/skills/secrets/SKILL.md

@@ -25,8 +25,12 @@ never copy a value into app code or client-visible state.
 3. If the app truly needs its own API key, register it with the shared secrets
    surface. Do not build a parallel key form or storage table.
 4. Use deployment configuration only for a secret owned by the deployed app,
-   such as a webhook verification secret. A deployment key must not stand in
-   for a user's or customer's provider credential.
+   such as a webhook verification secret. LLM inference keys are an app-owned
+   exception: self-hosted apps may use provider keys from deployment env as a
+   shared fallback, while scoped user or organization keys take precedence.
+   Hosted-workspace deployments backed by a shared database must not share
+   those env keys across apps or tenants. This exception does not authorize
+   using env credentials to access user-owned provider data.
 
 ## Register an app-local API key
 

package/dist/templates/workspace-core/.agents/skills/secrets/SKILL.md

@@ -25,8 +25,12 @@ never copy a value into app code or client-visible state.
 3. If the app truly needs its own API key, register it with the shared secrets
    surface. Do not build a parallel key form or storage table.
 4. Use deployment configuration only for a secret owned by the deployed app,
-   such as a webhook verification secret. A deployment key must not stand in
-   for a user's or customer's provider credential.
+   such as a webhook verification secret. LLM inference keys are an app-owned
+   exception: self-hosted apps may use provider keys from deployment env as a
+   shared fallback, while scoped user or organization keys take precedence.
+   Hosted-workspace deployments backed by a shared database must not share
+   those env keys across apps or tenants. This exception does not authorize
+   using env credentials to access user-owned provider data.
 
 ## Register an app-local API key
 

package/dist/triggers/actions/manage-automation.d.ts

@@ -29,10 +29,10 @@ declare const _default: import("../../action.js").ActionDefinition<{
     executionEngine?: undefined;
     executionCwd?: undefined;
 } | {
+    scope?: undefined;
     enabled?: undefined;
     nextRun?: undefined;
     created?: undefined;
-    scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
     deleted: boolean;
@@ -45,9 +45,9 @@ declare const _default: import("../../action.js").ActionDefinition<{
     executionCwd?: undefined;
     webhookPath?: undefined;
 } | {
+    scope?: undefined;
     deleted?: undefined;
     created?: undefined;
-    scope?: undefined;
     triggerType?: undefined;
     event?: undefined;
     name: string;

package/docs/content/deployment-environment-variables.mdx

@@ -58,16 +58,16 @@ platform when it is unset. Workspace and A2A settings are conditional on those
 features. Missing values either fail-closed or fall back to weaker behavior
 with a loud warning.
 
-| Variable                                    | Description                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BETTER_AUTH_SECRET`                        | 32+ char random string. Signs session cookies and is the fallback for `OAUTH_STATE_SECRET` and app-local encrypted values. It is also a legacy read candidate for existing shared vault ciphertext. Hard-required: the framework throws on startup if missing in production.                                                                       |
-| `BETTER_AUTH_URL`                           | Optional public origin override for this app (e.g. `https://mail.example.com`). The framework infers it from request, known-template, and hosting-platform context when unset.                                                                                                                                                                     |
-| `ANTHROPIC_API_KEY`                         | API key for the embedded production agent. **In multi-tenant deploys**, the framework refuses to fall back to this when the user has no per-user key. Bring-your-own-key is required. Single-tenant self-hosted installs use it as a global key.                                                                                                   |
-| `OAUTH_STATE_SECRET`                        | Dedicated HMAC key for OAuth state envelopes (Google, Atlassian, Zoom). Falls back to `BETTER_AUTH_SECRET` when unset, but a dedicated value is recommended so rotating one doesn't invalidate the other. Generate via `openssl rand -hex 32`.                                                                                                     |
-| `A2A_SECRET`                                | Shared HMAC for inter-app A2A JSON-RPC and signed background handoffs. Required for hosted workspace deploys and A2A features. Without it, those endpoints fail closed in production. When no dedicated workspace vault key is set, shared vault ciphertext uses a purpose-derived key from this value, so rotating it also rotates the vault key. |
-| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Preferred stable AES-256-GCM key for the shared encrypted-at-rest secrets vault. Set the same value in every app that reads the vault. It is separate from app-local OAuth/credential encryption, so A2A trust can rotate without stranding vault rows. Existing A2A-, Better Auth-, and app-key ciphertext is migrated on successful reads.       |
-| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Optional previous workspace vault key used only during a rotation window. Deploy it alongside the new `WORKSPACE_SECRETS_ENCRYPTION_KEY`, let successful reads re-encrypt rows, then remove it after migration.                                                                                                                                    |
-| `SECRETS_ENCRYPTION_KEY`                    | Legacy combined key for app-local encryption and the shared vault. It remains supported, but new multi-app deployments should use `WORKSPACE_SECRETS_ENCRYPTION_KEY` for the shared vault so changing workspace encryption does not change app-local OAuth ciphertext.                                                                             |
+| Variable                                    | Description                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BETTER_AUTH_SECRET`                        | 32+ char random string. Signs session cookies and is the fallback for `OAUTH_STATE_SECRET` and app-local encrypted values. It is also a legacy read candidate for existing shared vault ciphertext. Hard-required: the framework throws on startup if missing in production.                                                                                       |
+| `BETTER_AUTH_URL`                           | Optional public origin override for this app (e.g. `https://mail.example.com`). The framework infers it from request, known-template, and hosting-platform context when unset.                                                                                                                                                                                     |
+| `ANTHROPIC_API_KEY`                         | API key for the embedded agent. Self-hosted apps use deployment LLM provider keys as an app-wide fallback, including when using a remote database. Any signed-in user without a scoped key can use the deployment account across organizations, and usage is billed to that account. Production Hosted workspace runtimes block deployment provider-key fallbacks. |
+| `OAUTH_STATE_SECRET`                        | Dedicated HMAC key for OAuth state envelopes (Google, Atlassian, Zoom). Falls back to `BETTER_AUTH_SECRET` when unset, but a dedicated value is recommended so rotating one doesn't invalidate the other. Generate via `openssl rand -hex 32`.                                                                                                                     |
+| `A2A_SECRET`                                | Shared HMAC for inter-app A2A JSON-RPC and signed background handoffs. Required for hosted workspace deploys and A2A features. Without it, those endpoints fail closed in production. When no dedicated workspace vault key is set, shared vault ciphertext uses a purpose-derived key from this value, so rotating it also rotates the vault key.                 |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Preferred stable AES-256-GCM key for the shared encrypted-at-rest secrets vault. Set the same value in every app that reads the vault. It is separate from app-local OAuth/credential encryption, so A2A trust can rotate without stranding vault rows. Existing A2A-, Better Auth-, and app-key ciphertext is migrated on successful reads.                       |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Optional previous workspace vault key used only during a rotation window. Deploy it alongside the new `WORKSPACE_SECRETS_ENCRYPTION_KEY`, let successful reads re-encrypt rows, then remove it after migration.                                                                                                                                                    |
+| `SECRETS_ENCRYPTION_KEY`                    | Legacy combined key for app-local encryption and the shared vault. It remains supported, but new multi-app deployments should use `WORKSPACE_SECRETS_ENCRYPTION_KEY` for the shared vault so changing workspace encryption does not change app-local OAuth ciphertext.                                                                                             |
 
 ## Auth & Identity {#env-auth}