@agent-native/core 0.98.0 → 0.98.1

package/corpus/core/src/secrets/crypto.ts

@@ -5,12 +5,13 @@
  * credentials (`resolveCredential` / `saveCredential`, stored in `settings`) so
  * there is a single crypto implementation and a single key story.
  *
- * The encryption key is derived from `SECRETS_ENCRYPTION_KEY` (preferred) or the
- * existing `BETTER_AUTH_SECRET` env var (fallback so templates don't need a
- * second secret during development). In production we refuse to start without
- * one of them — a CWD-derived fallback would be effectively static (e.g.
- * `/var/task` on Lambda), so anyone with read access to the DB could decrypt
- * every secret.
+ * The encryption key is derived from `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when
+ * set, then `SECRETS_ENCRYPTION_KEY`, then `BETTER_AUTH_SECRET`. The app-scoped
+ * key lets a local multi-app workspace read one app's encrypted production data
+ * without replacing the shared local auth secret. In production we refuse to
+ * start without configured key material — a CWD-derived fallback would be
+ * effectively static (e.g. `/var/task` on Lambda), so anyone with read access
+ * to the DB could decrypt every secret.
  *
  * Encrypted values are tagged `v1:<iv-hex>:<ct-hex>:<tag-hex>`. The `v1:` prefix
  * lets readers distinguish ciphertext from legacy plaintext during migration.
@@ -55,6 +56,17 @@ function processCwd(): string {
   return process.cwd();
 }
 
+function appScopedEncryptionKey(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  const appName = process.env.APP_NAME?.trim() // guard:allow-env-credential — deploy-level app configuration selects the scoped encryption key.
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return appName
+    ? process.env[`${appName}_SECRETS_ENCRYPTION_KEY`] // guard:allow-env-credential — deploy-level app encryption material, never a user credential.
+    : undefined;
+}
+
 /**
  * Derive a 32-byte AES key from the configured secret material via SHA-256.
  * Re-derived per call (cheap, stateless, and makes rotation easy).
@@ -62,6 +74,7 @@ function processCwd(): string {
 export function getSecretEncryptionKey(): Buffer {
   const { createHash } = requireNodeCrypto();
   const explicit =
+    appScopedEncryptionKey() ||
     (typeof process === "undefined"
       ? undefined
       : process.env.SECRETS_ENCRYPTION_KEY) ||
@@ -71,9 +84,16 @@ export function getSecretEncryptionKey(): Buffer {
 
   if (!explicit) {
     if (processNodeEnv() === "production") {
+      const appName =
+        typeof process === "undefined"
+          ? undefined
+          : process.env.APP_NAME?.trim() // guard:allow-env-credential — deploy-level app configuration selects the scoped encryption key.
+              .toUpperCase()
+              .replace(/[^A-Z0-9]+/g, "_")
+              .replace(/^_+|_+$/g, "");
       throw new Error(
         "[agent-native/secrets] Refusing to start in production without an encryption key. " +
-          "Set SECRETS_ENCRYPTION_KEY (preferred) or BETTER_AUTH_SECRET in the deploy environment. " +
+          `Set ${appName ? `${appName}_SECRETS_ENCRYPTION_KEY, ` : ""}SECRETS_ENCRYPTION_KEY, or BETTER_AUTH_SECRET in the deploy environment. ` +
           "The previous CWD-derived fallback was effectively static (e.g. `/var/task` on Lambda), " +
           "which means anyone with read access to the secrets table could decrypt every user's secrets.",
       );
@@ -83,7 +103,7 @@ export function getSecretEncryptionKey(): Buffer {
       // eslint-disable-next-line no-console
       console.warn(
         "[agent-native/secrets] SECRETS_ENCRYPTION_KEY not set — using a machine-local fallback. " +
-          "Set SECRETS_ENCRYPTION_KEY (or BETTER_AUTH_SECRET) for production. " +
+          "Set an app-scoped *_SECRETS_ENCRYPTION_KEY, SECRETS_ENCRYPTION_KEY, or BETTER_AUTH_SECRET for production. " +
           "Production deploys without one of these env vars now hard-fail.",
       );
     }

package/corpus/core/src/server/action-change.ts

@@ -12,6 +12,7 @@ export interface NotifyActionChangeOptions {
   actionName: string;
   owner?: string;
   orgId?: string;
+  requestSource?: string;
 }
 
 function actionChangeTarget(
@@ -22,6 +23,7 @@ function actionChangeTarget(
     actionName: options.actionName,
     owner,
     orgId: owner ? undefined : (options.orgId ?? getRequestOrgId()),
+    requestSource: options.requestSource,
   };
 }
 
@@ -38,7 +40,7 @@ export async function writeActionChangeMarker(
       ...actionChangeMarkerValue(target),
       nonce: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
     },
-    { requestSource: "agent" },
+    { requestSource: options.requestSource ?? "agent" },
   );
 }
 
@@ -52,11 +54,13 @@ export async function notifyActionChange(
     key: options.actionName,
     ...(target.owner ? { owner: target.owner } : {}),
     ...(target.orgId ? { orgId: target.orgId } : {}),
+    ...(options.requestSource ? { requestSource: options.requestSource } : {}),
   });
 
   await writeActionChangeMarker({
     actionName: options.actionName,
     ...(target.owner ? { owner: target.owner } : {}),
     ...(target.orgId ? { orgId: target.orgId } : {}),
+    ...(options.requestSource ? { requestSource: options.requestSource } : {}),
   });
 }

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

@@ -371,6 +371,14 @@ export function mountActionRoutes(
                   await notifyActionChange({
                     actionName: name,
                     ...(userEmail ? { owner: userEmail } : {}),
+                    ...(getHeader(event, "x-request-source")
+                      ? {
+                          requestSource: getHeader(
+                            event,
+                            "x-request-source",
+                          ) as string,
+                        }
+                      : {}),
                   });
                 } catch {
                   // ignore

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

@@ -604,6 +604,7 @@ function recordActionChanges(targets: ActionChangeTarget[]): void {
       key: target.actionName ?? "*",
       ...(target.owner ? { owner: target.owner } : {}),
       ...(target.orgId ? { orgId: target.orgId } : {}),
+      ...(target.requestSource ? { requestSource: target.requestSource } : {}),
     });
   }
 }

package/corpus/core/src/server/realtime-voice.ts

@@ -18,6 +18,8 @@ import {
   sanitizeToolErrorText,
   sanitizeToolErrorValue,
 } from "../agent/tool-error-redaction.js";
+import { TOOL_SEARCH_ACTION_NAME } from "../agent/tool-search.js";
+import { parseAcceptLanguage } from "../localization/server.js";
 import { getSession } from "./auth.js";
 import {
   getBuilderGatewayBaseUrl,
@@ -37,6 +39,10 @@ export const REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS = 16_000;
 export const REALTIME_VOICE_MAX_TOOLS = 32;
 export const REALTIME_VOICE_MAX_TOOL_SCHEMA_BYTES = 32_000;
 export const REALTIME_VOICE_MAX_SESSION_BYTES = 64_000;
+export const REALTIME_VOICE_TOOL_GRANT_TTL_MS = 10 * 60 * 1_000;
+export const REALTIME_VOICE_MAX_TOOL_GRANT_SESSIONS = 256;
+export const REALTIME_VOICE_CAPABILITY_HEADER =
+  "X-Agent-Native-Realtime-Capability";
 
 const OPENAI_REALTIME_CALLS_URL = "https://api.openai.com/v1/realtime/calls";
 const DEFAULT_MODEL = "gpt-realtime-2.1";
@@ -50,6 +56,37 @@ const REALTIME_TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const CALL_ID = /^[A-Za-z0-9_-]{1,256}$/;
 const SESSION_ID = /^[A-Za-z0-9_.:-]{1,256}$/;
 const BROWSER_TAB_ID = /^[A-Za-z0-9_-]{1,96}$/;
+const ISO_639_1_LANGUAGE = /^[A-Za-z]{2}$/;
+const REALTIME_VOICE_BUILT_INS = new Set([
+  "alloy",
+  "ash",
+  "ballad",
+  "coral",
+  "echo",
+  "sage",
+  "shimmer",
+  "verse",
+  "marin",
+  "cedar",
+]);
+const REALTIME_VOICE_REASONING_EFFORT = {
+  instant: "minimal",
+  balanced: "low",
+  deep: "medium",
+} as const;
+
+/**
+ * Realtime sessions have a deliberately bounded tool manifest. Keep the
+ * context/navigation tools ahead of large template registries so voice can
+ * always see and operate the same UI navigation surface as text chat.
+ */
+const REALTIME_VOICE_PRIORITY_TOOLS = [
+  "navigate",
+  "set-url-path",
+  "set-search-params",
+  "view-screen",
+  TOOL_SEARCH_ACTION_NAME,
+] as const;
 
 export interface RealtimeVoiceRequestContext {
   event: H3Event;
@@ -105,6 +142,17 @@ interface RealtimeFunctionTool {
   parameters: Record<string, unknown>;
 }
 
+interface RealtimeToolCapability {
+  userEmail: string;
+  orgId?: string;
+  browserTabId?: string;
+  expiresAt: number;
+  initialNames: Set<string>;
+  names: Set<string>;
+}
+
+type RealtimeToolCapabilityStore = Map<string, RealtimeToolCapability>;
+
 interface AuthenticatedVoiceContext extends RealtimeVoiceRequestContext {
   timezone?: string;
 }
@@ -126,6 +174,50 @@ function configuredIdentifier(
     : fallback;
 }
 
+export function resolveRealtimeVoiceTranscriptionLanguage(
+  acceptLanguage: string | null | undefined,
+): string {
+  for (const locale of parseAcceptLanguage(acceptLanguage)) {
+    const primaryLanguage = locale.split("-")[0];
+    if (ISO_639_1_LANGUAGE.test(primaryLanguage)) {
+      return primaryLanguage.toLowerCase();
+    }
+  }
+  return "en";
+}
+
+export function resolveRealtimeVoiceLanguagePreference(
+  value: string | null | undefined,
+  acceptLanguage: string | null | undefined,
+): string {
+  const normalized = value?.trim().toLowerCase();
+  return normalized && ISO_639_1_LANGUAGE.test(normalized)
+    ? normalized
+    : resolveRealtimeVoiceTranscriptionLanguage(acceptLanguage);
+}
+
+export function resolveRealtimeVoiceReasoningEffort(
+  value: string | null | undefined,
+): "minimal" | "low" | "medium" {
+  const normalized = value?.trim().toLowerCase();
+  return normalized &&
+    Object.hasOwn(REALTIME_VOICE_REASONING_EFFORT, normalized)
+    ? REALTIME_VOICE_REASONING_EFFORT[
+        normalized as keyof typeof REALTIME_VOICE_REASONING_EFFORT
+      ]
+    : "low";
+}
+
+export function resolveRealtimeVoicePreference(
+  value: string | null | undefined,
+  fallback: string,
+): string {
+  const normalized = value?.trim().toLowerCase();
+  return normalized && REALTIME_VOICE_BUILT_INS.has(normalized)
+    ? normalized
+    : fallback;
+}
+
 function truncate(value: string, maxChars: number): string {
   if (value.length <= maxChars) return value;
   return `${value.slice(0, maxChars)}\n\n...[truncated]`;
@@ -218,7 +310,22 @@ function buildRealtimeTools(
       parameters,
     });
   }
-  return tools;
+  const priority = new Map<string, number>(
+    REALTIME_VOICE_PRIORITY_TOOLS.map((name, index) => [name, index]),
+  );
+  return tools
+    .map((tool, index) => ({ tool, index }))
+    .sort((left, right) => {
+      const leftPriority = priority.get(left.tool.name);
+      const rightPriority = priority.get(right.tool.name);
+      if (leftPriority !== undefined || rightPriority !== undefined) {
+        if (leftPriority === undefined) return 1;
+        if (rightPriority === undefined) return -1;
+        return leftPriority - rightPriority;
+      }
+      return left.index - right.index;
+    })
+    .map(({ tool }) => tool);
 }
 
 function packRealtimeTools(
@@ -243,6 +350,124 @@ function packRealtimeTools(
   return packed;
 }
 
+function mintRealtimeToolCapability(): string {
+  return globalThis.crypto.randomUUID().replaceAll("-", "");
+}
+
+function cleanRealtimeToolCapabilities(
+  capabilities: RealtimeToolCapabilityStore,
+  now = Date.now(),
+): void {
+  for (const [key, capability] of capabilities) {
+    if (capability.expiresAt <= now) capabilities.delete(key);
+  }
+  while (capabilities.size > REALTIME_VOICE_MAX_TOOL_GRANT_SESSIONS) {
+    let oldestKey: string | undefined;
+    let oldestExpiry = Number.POSITIVE_INFINITY;
+    for (const [key, capability] of capabilities) {
+      if (capability.expiresAt < oldestExpiry) {
+        oldestKey = key;
+        oldestExpiry = capability.expiresAt;
+      }
+    }
+    if (!oldestKey) break;
+    capabilities.delete(oldestKey);
+  }
+}
+
+function registerRealtimeToolCapability(
+  capabilities: RealtimeToolCapabilityStore,
+  auth: AuthenticatedVoiceContext,
+  initialNames: Iterable<string>,
+): string {
+  cleanRealtimeToolCapabilities(capabilities);
+  const token = mintRealtimeToolCapability();
+  capabilities.set(token, {
+    userEmail: auth.userEmail.trim().toLowerCase(),
+    ...(auth.orgId ? { orgId: auth.orgId } : {}),
+    ...(auth.browserTabId ? { browserTabId: auth.browserTabId } : {}),
+    expiresAt: Date.now() + REALTIME_VOICE_TOOL_GRANT_TTL_MS,
+    initialNames: new Set(initialNames),
+    names: new Set(),
+  });
+  cleanRealtimeToolCapabilities(capabilities);
+  return token;
+}
+
+function resolveRealtimeToolCapability(
+  capabilities: RealtimeToolCapabilityStore,
+  token: string | undefined,
+  auth: AuthenticatedVoiceContext,
+): RealtimeToolCapability | null {
+  cleanRealtimeToolCapabilities(capabilities);
+  if (!token) return null;
+  const capability = capabilities.get(token);
+  if (!capability) return null;
+  if (
+    capability.userEmail !== auth.userEmail.trim().toLowerCase() ||
+    capability.orgId !== auth.orgId ||
+    capability.browserTabId !== auth.browserTabId
+  ) {
+    return null;
+  }
+  capability.expiresAt = Date.now() + REALTIME_VOICE_TOOL_GRANT_TTL_MS;
+  return capability;
+}
+
+function parseSuccessfulToolSearchNames(output: string): string[] {
+  try {
+    const parsed = JSON.parse(output) as { results?: unknown };
+    if (!Array.isArray(parsed.results)) return [];
+    const names: string[] = [];
+    for (const result of parsed.results) {
+      if (!isRecord(result) || typeof result.name !== "string") continue;
+      if (!REALTIME_TOOL_NAME.test(result.name)) continue;
+      if (!names.includes(result.name)) names.push(result.name);
+      if (names.length >= REALTIME_VOICE_MAX_TOOLS) break;
+    }
+    return names;
+  } catch {
+    return [];
+  }
+}
+
+function grantDiscoveredRealtimeTools(input: {
+  request: NonNullable<ReturnType<typeof parseToolRequest>>;
+  result: RealtimeVoiceToolExecutionResult;
+  toolsByName: ReadonlyMap<string, RealtimeFunctionTool>;
+  initialAllowedNames: ReadonlySet<string>;
+  capability: RealtimeToolCapability;
+}): RealtimeFunctionTool[] {
+  const query = input.request.args.query;
+  if (
+    input.request.name !== TOOL_SEARCH_ACTION_NAME ||
+    input.result.status !== "completed" ||
+    typeof query !== "string" ||
+    !query.trim()
+  ) {
+    return [];
+  }
+
+  const candidates = parseSuccessfulToolSearchNames(input.result.output)
+    .filter((name) => !input.initialAllowedNames.has(name))
+    .map((name) => input.toolsByName.get(name))
+    .filter((tool): tool is RealtimeFunctionTool => Boolean(tool));
+  const boundedTools = packRealtimeTools({}, candidates);
+  const expandedTools: RealtimeFunctionTool[] = [];
+  for (const tool of boundedTools) {
+    if (
+      !input.capability.names.has(tool.name) &&
+      input.capability.names.size >= REALTIME_VOICE_MAX_TOOLS
+    ) {
+      continue;
+    }
+    input.capability.names.add(tool.name);
+    expandedTools.push(tool);
+  }
+  input.capability.expiresAt = Date.now() + REALTIME_VOICE_TOOL_GRANT_TTL_MS;
+  return expandedTools;
+}
+
 function declaredBodyBytes(event: H3Event): number | undefined {
   const raw = readSafeHeader(event, "content-length");
   if (!raw) return undefined;
@@ -328,6 +553,7 @@ function invalidMethod(event: H3Event): { error: string } {
 
 function createSessionHandler(
   tools: RealtimeFunctionTool[],
+  capabilities: RealtimeToolCapabilityStore,
   options: MountRealtimeVoiceRoutesOptions,
 ) {
   return defineEventHandler(async (event: H3Event) => {
@@ -394,14 +620,30 @@ function createSessionHandler(
         }
 
         const instructions = await buildInstructions(auth, options);
+        const transcriptionLanguage = resolveRealtimeVoiceLanguagePreference(
+          readSafeHeader(event, "x-agent-native-realtime-language"),
+          readSafeHeader(event, "accept-language"),
+        );
+        const reasoningEffort = resolveRealtimeVoiceReasoningEffort(
+          readSafeHeader(event, "x-agent-native-realtime-intelligence"),
+        );
+        const voice = resolveRealtimeVoicePreference(
+          readSafeHeader(event, "x-agent-native-realtime-voice"),
+          configuredIdentifier(options.voice, DEFAULT_VOICE),
+        );
         const sessionBase = {
           type: "realtime",
           model: configuredIdentifier(options.model, DEFAULT_MODEL),
           instructions,
+          parallel_tool_calls: false,
+          reasoning: { effort: reasoningEffort },
           output_modalities: ["audio"],
           audio: {
             input: {
-              transcription: { model: "gpt-4o-mini-transcribe" },
+              transcription: {
+                model: "gpt-4o-mini-transcribe",
+                language: transcriptionLanguage,
+              },
               turn_detection: {
                 type: "semantic_vad",
                 create_response: true,
@@ -410,13 +652,14 @@ function createSessionHandler(
               },
             },
             output: {
-              voice: configuredIdentifier(options.voice, DEFAULT_VOICE),
+              voice,
             },
           },
         };
+        const packedTools = packRealtimeTools(sessionBase, tools);
         const session = {
           ...sessionBase,
-          tools: packRealtimeTools(sessionBase, tools),
+          tools: packedTools,
           tool_choice: "auto",
         };
 
@@ -491,6 +734,15 @@ function createSessionHandler(
 
         setResponseStatus(event, upstream.status);
         setResponseHeader(event, "Content-Type", "application/sdp");
+        setResponseHeader(
+          event,
+          REALTIME_VOICE_CAPABILITY_HEADER,
+          registerRealtimeToolCapability(
+            capabilities,
+            auth,
+            packedTools.map((tool) => tool.name),
+          ),
+        );
         return answerSdp;
       },
     );
@@ -562,7 +814,8 @@ function normalizeExecutionResult(
 }
 
 function createToolHandler(
-  allowedToolNames: ReadonlySet<string>,
+  toolsByName: ReadonlyMap<string, RealtimeFunctionTool>,
+  capabilities: RealtimeToolCapabilityStore,
   options: MountRealtimeVoiceRoutesOptions,
 ) {
   return defineEventHandler(async (event: H3Event) => {
@@ -578,6 +831,15 @@ function createToolHandler(
       setResponseStatus(event, 401);
       return { error: "Authentication required" };
     }
+    const capability = resolveRealtimeToolCapability(
+      capabilities,
+      readSafeHeader(event, REALTIME_VOICE_CAPABILITY_HEADER),
+      auth,
+    );
+    if (!capability) {
+      setResponseStatus(event, 403);
+      return { error: "Invalid or expired realtime voice capability" };
+    }
 
     const contentType = readSafeHeader(event, "content-type")?.toLowerCase();
     if (!contentType?.includes("application/json")) {
@@ -608,12 +870,22 @@ function createToolHandler(
       setResponseStatus(event, 400);
       return { error: "Invalid realtime tool request" };
     }
-    if (!allowedToolNames.has(request.name)) {
+    if (
+      request.browserTabId !== undefined &&
+      request.browserTabId !== capability.browserTabId
+    ) {
+      setResponseStatus(event, 403);
+      return { error: "Realtime voice browser tab mismatch" };
+    }
+    if (
+      !capability.initialNames.has(request.name) &&
+      !capability.names.has(request.name)
+    ) {
       setResponseStatus(event, 404);
       return { error: "Unknown realtime voice tool" };
     }
 
-    const browserTabId = request.browserTabId ?? auth.browserTabId;
+    const browserTabId = capability.browserTabId;
     const threadId = request.sessionId
       ? `realtime:${request.sessionId}`
       : `realtime:${request.callId}`;
@@ -635,9 +907,21 @@ function createToolHandler(
               userEmail: auth.userEmail,
               orgId: auth.orgId,
               ...request,
+              ...(browserTabId ? { browserTabId } : {}),
             }),
           );
-          return { callId: request.callId, ...result };
+          const expandedTools = grantDiscoveredRealtimeTools({
+            request,
+            result,
+            toolsByName,
+            initialAllowedNames: capability.initialNames,
+            capability,
+          });
+          return {
+            callId: request.callId,
+            ...result,
+            ...(expandedTools.length > 0 ? { expandedTools } : {}),
+          };
         } catch (error) {
           setResponseStatus(event, 500);
           return {
@@ -665,14 +949,16 @@ export function mountRealtimeVoiceRoutes(
   }
 
   const tools = buildRealtimeTools(actions);
-  const allowedToolNames = new Set(
-    tools.slice(0, REALTIME_VOICE_MAX_TOOLS).map((tool) => tool.name),
-  );
+  const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
+  const capabilities: RealtimeToolCapabilityStore = new Map();
   const app = getH3App(nitroApp);
-  app.use(REALTIME_VOICE_SESSION_PATH, createSessionHandler(tools, options));
+  app.use(
+    REALTIME_VOICE_SESSION_PATH,
+    createSessionHandler(tools, capabilities, options),
+  );
   app.use(
     REALTIME_VOICE_TOOL_PATH,
-    createToolHandler(allowedToolNames, options),
+    createToolHandler(toolsByName, capabilities, options),
   );
   return {
     sessionPath: REALTIME_VOICE_SESSION_PATH,

package/corpus/core/src/styles/agent-native.css

@@ -733,7 +733,7 @@
 }
 
 .agent-composer-root--hero {
-  min-height: 7.5rem;
+  min-height: 5.625rem;
   border-radius: 1rem;
   border-color: hsl(var(--border) / 0.75);
   background: hsl(var(--muted) / 0.62);
@@ -751,7 +751,7 @@
 }
 
 .agent-composer-root--hero [data-agent-composer-slot="editor-input"] {
-  min-height: 4rem;
+  min-height: 3rem;
   font-size: 1rem;
   line-height: 1.75rem;
 }

package/corpus/core/src/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/core/src/templates/workspace-core/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

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

@@ -170,9 +170,13 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
 - Values are stored in `app_secrets` (created on-demand; no migration
   needed).
 - Encrypted at rest with AES-256-GCM. Key material is derived from
-  `SECRETS_ENCRYPTION_KEY` (preferred) or `BETTER_AUTH_SECRET` (fallback).
-  If neither is set, the framework uses a machine-local fallback and logs a
-  one-time warning — set `SECRETS_ENCRYPTION_KEY` in production.
+  `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set (for example,
+  `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
+  `BETTER_AUTH_SECRET`. App-scoped keys are useful when a local multi-app
+  workspace connects one app to its production database without replacing the
+  shared local authentication secret. If none is set, the framework uses a
+  machine-local fallback and logs a one-time warning — set stable key material
+  in production and in every runtime that reads the same encrypted data.
 
 ## Ad-hoc Keys