@agent-native/core 0.131.6 → 0.131.7

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

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

package/docs/content/deployment.mdx

@@ -536,14 +536,16 @@ Database connection variables (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, per-app `<
 
 These must be set before promoting an app to a real prod deploy. Missing values either fail-closed (the framework refuses to start / refuses to handle requests) 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`        | Public origin of this app (e.g. `https://mail.example.com`). Used for cookie domain and OAuth redirect construction.                                                                                                                                                                                                                                                             |
-| `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. Without it, every A2A endpoint and the `/_agent-native/integrations/process-task` self-fire endpoint return 503 in production. When `SECRETS_ENCRYPTION_KEY` is unset, shared vault ciphertext uses a purpose-derived key from this value, so rotating it also rotates the vault key.                                                    |
-| `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. Shared vault reads fall back to purpose-derived `A2A_SECRET`, then legacy Better Auth and app-scoped keys. Before rotating A2A, add this key everywhere and read/migrate every existing row while the old A2A material remains available. |
+| 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`                           | Public origin of this app (e.g. `https://mail.example.com`). Used for cookie domain and OAuth redirect construction.                                                                                                                                                                                                                         |
+| `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. Without it, every A2A endpoint and the `/_agent-native/integrations/process-task` self-fire endpoint return 503 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}
 
@@ -563,13 +565,13 @@ Inside a workspace, the root `.env` is loaded into every app automatically, so s
 
 ### Generating Strong Secrets {#env-generate-secrets}
 
-For any secret marked "32+ char random" (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `SECRETS_ENCRYPTION_KEY`, `AGENT_NATIVE_BUILDER_RELAY_SECRET`), generate fresh values with:
+For any secret marked "32+ char random" (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `WORKSPACE_SECRETS_ENCRYPTION_KEY`, `SECRETS_ENCRYPTION_KEY`, `AGENT_NATIVE_BUILDER_RELAY_SECRET`), generate fresh values with:
 
 ```bash
 openssl rand -hex 32
 ```
 
-Rotate them by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again.
+Rotate signing/session keys by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again. Rotate `WORKSPACE_SECRETS_ENCRYPTION_KEY` with the `..._PREVIOUS` window described above so encrypted vault rows remain readable while they migrate.
 
 ## Production Agent Tools {#production-agent-tools}
 

package/docs/content/security.mdx

@@ -320,7 +320,7 @@ pnpm action db-check-scoping --require-org  # Also require org_id
 | OAuth tokens (Google, GitHub)      | `oauth_tokens` store via `saveOAuthTokens()`               |
 | Session tokens                     | Automatic (Better Auth handles this)                       |
 
-Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) checks `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` first, then on a hosted workspace deploy falls back further to material derived from `A2A_SECRET`, and only then to the app-scoped key as a last resort. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
+Per-user/per-org credentials and the vault are encrypted at rest with AES-256-GCM. For a per-user/per-org credential, the key precedence is `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (app-scoped — useful in a multi-app workspace where apps shouldn't share one key) → `SECRETS_ENCRYPTION_KEY` → `BETTER_AUTH_SECRET`; production refuses to start without one of these set. The shared workspace vault (`app_secrets`, meant to decrypt the same in sibling apps) prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy combined `SECRETS_ENCRYPTION_KEY`, then material derived from `A2A_SECRET`, with `BETTER_AUTH_SECRET` and the app-scoped key retained as compatibility candidates. Successful fallback reads compare-and-swap re-encrypt the shared column under the preferred key. During a workspace-key rotation, set `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` to the old value until reads have migrated existing rows. To encrypt any pre-existing plaintext credential rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive).
 
 Never store secrets in `settings`, `application_state`, source code, or action responses. Use the credential / vault APIs above — they handle both encryption and per-user scoping.
 
@@ -365,7 +365,7 @@ Google Docs Pub/Sub push notifications don't go through that generic adapter gat
 - [ ] `BETTER_AUTH_SECRET` set to a random 32+ char string (`openssl rand -hex 32`), unless this is a hosted workspace deploy deriving it from `A2A_SECRET`
 - [ ] `OAUTH_STATE_SECRET` set to a separate random 32+ char string (don't reuse `BETTER_AUTH_SECRET`) — see [OAuth State Signing](#oauth-state)
 - [ ] `A2A_SECRET` set on every app that calls or receives A2A traffic — see [A2A Identity Verification](#a2a-identity)
-- [ ] `SECRETS_ENCRYPTION_KEY` set (or rely on the `BETTER_AUTH_SECRET` fallback) — see [Secrets Management](#secrets)
+- [ ] `WORKSPACE_SECRETS_ENCRYPTION_KEY` set consistently for multi-app shared vaults; app-local encryption still has `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` fallbacks — see [Secrets Management](#secrets)
 - [ ] `AUTH_SKIP_EMAIL_VERIFICATION` is **not** set in production (or set only on QA preview deploys)
 
 ### Webhook secrets (set the ones for integrations you use)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.131.6",
+  "version": "0.131.7",
   "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": {
@@ -395,8 +395,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.12.0"
+    "@agent-native/toolkit": "^0.12.0",
+    "@agent-native/recap-cli": "0.5.1"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/a2a/invoke.ts

@@ -263,9 +263,11 @@ export function buildAgentInvocationPrompt(
 ): string {
   return (
     `${prompt}\n\n` +
-    `[Note: this request comes from another app via A2A. The caller cannot see your local UI, resource list, or navigation - only the literal text you put in your reply. ` +
+    `<a2a-caller-hint>\n` +
+    `This request comes from another app via A2A. The caller cannot see your local UI, resource list, or navigation - only the literal text you put in your reply. ` +
     `If you create or reference a deck/document/design/dashboard/resource, include its FULLY-QUALIFIED URL (e.g. ${agentUrl.replace(/\/$/, "")}/<path>/<id>) in your reply, not a relative path. ` +
-    `Use only artifact IDs and URL paths returned by successful actions - never invent slugs, IDs, or hosts.]`
+    `Use only artifact IDs and URL paths returned by successful actions - never invent slugs, IDs, or hosts.\n` +
+    `</a2a-caller-hint>`
   );
 }
 

package/src/agent/action-continuation-guidance.ts

@@ -21,8 +21,9 @@ export function incrementalActionGuidance(tool: string): string | undefined {
     case "create-prototype-plan":
       return "create the plan with its core sections or first screen, then expand it with `update-visual-plan`/`patch-visual-plan-source` follow-up edits";
     case "update-visual-plan":
+      return "apply one or a few small `update-visual-plan` `contentPatches` such as `append-block`, `update-rich-text`, or a text patch; do not resend the full plan or switch to a source-control workflow";
     case "patch-visual-plan-source":
-      return "apply smaller, targeted `patch-visual-plan-source` edits rather than rewriting the whole plan in one call";
+      return "apply small targeted `patch-visual-plan-source` MDX AST edits; do not use `replace-file`, and do not use this source action for a live plan edit";
     case "update-dashboard":
       return "save a small dashboard first, then add panels one at a time with `update-dashboard` incremental `ops` edits instead of authoring the whole config in one call";
     default:

package/src/agent/engine/registry.ts

@@ -600,6 +600,41 @@ async function resolveUsableProviderSecret(
   return authFailure ? null : value;
 }
 
+/**
+ * Return true only when the supplied key can be positively identified as a
+ * usable credential for a different registered provider.
+ *
+ * `ResolveEngineConfig.apiKey` is public and may be an opaque caller-provided
+ * key, so automatic selection must not silently replace it merely because a
+ * stored credential also exists. Delegated/internal callers, however,
+ * historically pass the current "active" provider key before the registry
+ * selects an app-default engine. Exact in-memory comparison lets us correct
+ * that proven mismatch without guessing from provider-specific key prefixes
+ * or exposing either value.
+ */
+async function apiKeyBelongsToDifferentProvider(
+  apiKey: string,
+  selectedEntry: AgentEngineEntry,
+): Promise<boolean> {
+  const selectedEnvVars = new Set(selectedEntry.requiredEnvVars);
+  const checkedEnvVars = new Set<string>();
+  for (const entry of _registry.values()) {
+    if (entry === selectedEntry || entry.name === "builder") continue;
+    for (const key of entry.requiredEnvVars) {
+      if (selectedEnvVars.has(key) || checkedEnvVars.has(key)) continue;
+      checkedEnvVars.add(key);
+      try {
+        if ((await resolveUsableProviderSecret(key)) === apiKey) return true;
+      } catch {
+        // An unrelated provider store failure is not proof that the explicit
+        // key belongs elsewhere. Preserve the caller's key and let the
+        // selected provider's own preflight report any relevant failure.
+      }
+    }
+  }
+  return false;
+}
+
 async function engineCreateConfigForEntry(
   entry: AgentEngineEntry,
   apiKey: string | undefined,
@@ -612,27 +647,44 @@ async function engineCreateConfigForEntry(
   // Callers historically passed one untagged "active" key before the registry
   // chose an engine, which could hand an Anthropic key to an app-default
   // OpenAI engine (or vice versa). Explicit engineOption branches retain their
-  // paired key; automatic branches opt into matching the chosen provider here.
+  // paired key. Automatic branches replace only a key proven to belong to a
+  // different configured provider; opaque caller-supplied keys keep the public
+  // `ResolveEngineConfig.apiKey` contract.
   if (
     preferResolvedCredential &&
     entry.name !== "builder" &&
     entry.requiredEnvVars.length > 0
   ) {
-    let foundMatchingCredential = false;
+    let resolvedMatchingCredential: string | undefined;
+    let matchingCredentialUsesDeployFallback = false;
     for (const key of entry.requiredEnvVars) {
       const resolved = (await resolveUsableProviderSecret(key)) ?? undefined;
       if (!resolved) continue;
-      foundMatchingCredential = true;
-      const deployFallback =
+      resolvedMatchingCredential = resolved;
+      matchingCredentialUsesDeployFallback =
         canUseDeployCredentialFallbackForRequest(key) &&
         readDeployCredentialEnv(key) === resolved;
+      break;
+    }
+
+    const suppliedKeyMatchesSelected =
+      matchingApiKey !== undefined &&
+      matchingApiKey === resolvedMatchingCredential;
+    const suppliedKeyBelongsElsewhere =
+      matchingApiKey !== undefined &&
+      !suppliedKeyMatchesSelected &&
+      (await apiKeyBelongsToDifferentProvider(matchingApiKey, entry));
+
+    if (matchingApiKey === undefined || suppliedKeyBelongsElsewhere) {
       // Keep deploy-only credentials implicit so provider SDKs retain their
       // established env-fallback behavior. Scoped credentials must be passed
-      // explicitly, and replace an unrelated preselected provider key.
-      if (matchingApiKey || !deployFallback) matchingApiKey = resolved;
-      break;
+      // explicitly. A proven different-provider key is replaced or cleared;
+      // an opaque caller-supplied key is preserved by the branch above.
+      matchingApiKey =
+        resolvedMatchingCredential && !matchingCredentialUsesDeployFallback
+          ? resolvedMatchingCredential
+          : undefined;
     }
-    if (!foundMatchingCredential) matchingApiKey = undefined;
   }
   if (entry.name === "ai-sdk:openai") {
     if (typeof safeExtra.baseURL === "string" && safeExtra.baseUrl == null) {
@@ -924,7 +976,7 @@ export async function resolveEngine(
     );
   }
   return anthropicEntry.create(
-    await engineCreateConfigForEntry(anthropicEntry, apiKey),
+    await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, true),
   );
 }
 

package/src/guards/no-env-credentials.ts

@@ -65,6 +65,8 @@ const ALLOWLIST_EXACT = new Set([
   "PORT",
   "HOST",
   "SECRETS_ENCRYPTION_KEY",
+  "WORKSPACE_SECRETS_ENCRYPTION_KEY",
+  "WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS",
 ]);
 
 const ALLOWLIST_PREFIX = [

package/src/scripts/call-agent.ts

@@ -464,10 +464,12 @@ export async function run(
   const messageWithHint = taskId
     ? ""
     : `${message}${integrationSourceContextHint(sourceContext)}\n\n` +
-      `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
+      `<a2a-caller-hint>\n` +
+      `This request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
       `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
       `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts. ` +
-      `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.]`;
+      `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.\n` +
+      `</a2a-caller-hint>`;
 
   const invocationId = randomUUID();
   const invocationStartedAt = Date.now();

package/src/secrets/crypto.ts

@@ -13,10 +13,13 @@
  * The generic encryption key is derived from
  * `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set, then
  * `SECRETS_ENCRYPTION_KEY`, then `BETTER_AUTH_SECRET`. Workspace-shared vault
- * rows use a different precedence: `SECRETS_ENCRYPTION_KEY`, then material
- * derived from the workspace-wide `A2A_SECRET`, then the app-local auth/key
- * fallbacks retained for backward-compatible reads. This keeps sibling apps
- * on one key even when each app correctly has a different auth secret.
+ * rows use a different precedence: `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then
+ * the legacy shared `SECRETS_ENCRYPTION_KEY`, then material derived from the
+ * workspace-wide `A2A_SECRET`, then the app-local auth/key fallbacks retained
+ * for backward-compatible reads. A previous workspace key can be supplied
+ * during rotation with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS`. This keeps
+ * sibling apps on one stable key even when each app correctly has a different
+ * auth secret, and prevents A2A trust rotation from stranding vault data.
  *
  * In production we refuse to start without configured key material — a
  * CWD-derived fallback would be effectively static (e.g. `/var/task` on
@@ -95,6 +98,18 @@ function genericEncryptionKeyMaterial(): string | undefined {
   );
 }
 
+function workspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY?.trim() || undefined;
+}
+
+function previousWorkspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return (
+    process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS?.trim() || undefined
+  );
+}
+
 /**
  * Vault sharing follows configured A2A trust even on independently deployed
  * sibling apps that are not launched by the workspace wrapper. The wrapper's
@@ -116,14 +131,17 @@ function a2aSharedEncryptionKeyMaterial(): string | undefined {
  * Stable materials that may be used for workspace-shared vault rows, ordered
  * from current preference to legacy compatibility fallbacks.
  *
- * `BETTER_AUTH_SECRET` deliberately comes after the A2A-derived material:
- * sibling apps normally have different auth secrets but share A2A trust.
+ * `BETTER_AUTH_SECRET` deliberately comes after the workspace and A2A-derived
+ * materials: sibling apps normally have different auth secrets but share
+ * workspace trust.
  */
 function sharedEncryptionKeyMaterials(): string[] {
   if (typeof process === "undefined") return [];
   const candidates = [
+    workspaceSharedEncryptionKeyMaterial(),
     process.env.SECRETS_ENCRYPTION_KEY,
     a2aSharedEncryptionKeyMaterial(),
+    previousWorkspaceSharedEncryptionKeyMaterial(),
     process.env.BETTER_AUTH_SECRET,
     appScopedEncryptionKey(),
   ].filter((value): value is string => Boolean(value));
@@ -131,7 +149,14 @@ function sharedEncryptionKeyMaterials(): string[] {
 }
 
 function preferredSharedEncryptionKeyMaterial(): string | undefined {
-  return sharedEncryptionKeyMaterials()[0];
+  if (typeof process === "undefined") return undefined;
+  return (
+    workspaceSharedEncryptionKeyMaterial() ||
+    process.env.SECRETS_ENCRYPTION_KEY ||
+    a2aSharedEncryptionKeyMaterial() ||
+    process.env.BETTER_AUTH_SECRET ||
+    appScopedEncryptionKey()
+  );
 }
 
 function hashSecretEncryptionKey(material: string): Buffer {
@@ -187,20 +212,23 @@ export function getSecretEncryptionKey(): Buffer {
 /**
  * Derive the preferred workspace-shared key used by `app_secrets` rows.
  * Unlike generic column-level encryption, workspace vault data must decrypt
- * in sibling apps. An explicit `SECRETS_ENCRYPTION_KEY` wins; hosted
- * workspaces otherwise derive stable material from their shared `A2A_SECRET`
- * before considering app-local `BETTER_AUTH_SECRET` or app-scoped key
- * fallbacks. Reads try every configured legacy candidate and report when the
- * ciphertext should be refreshed under the preferred key.
+ * in sibling apps. An explicit `WORKSPACE_SECRETS_ENCRYPTION_KEY` wins without
+ * changing the key for app-local OAuth and credential ciphertext. The legacy
+ * shared `SECRETS_ENCRYPTION_KEY` remains supported; hosted workspaces
+ * otherwise derive material from their shared `A2A_SECRET` before considering
+ * app-local `BETTER_AUTH_SECRET` or app-scoped key fallbacks. Reads try every
+ * configured legacy/previous candidate and report when the ciphertext should
+ * be refreshed under the preferred key.
  */
 export function getSharedSecretEncryptionKey(): Buffer {
   return deriveSecretEncryptionKey(
     preferredSharedEncryptionKeyMaterial(),
     "[agent-native/secrets] Refusing to start in production without encryption key material for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, or set BETTER_AUTH_SECRET / an app-scoped " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY (preferred), SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, " +
+      "or set BETTER_AUTH_SECRET / an app-scoped " +
       "*_SECRETS_ENCRYPTION_KEY compatibility fallback in the deploy environment.",
-    "[agent-native/secrets] SECRETS_ENCRYPTION_KEY not set — using app-scoped or machine-local fallback for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
+    "[agent-native/secrets] Workspace encryption key not set — using app-scoped or machine-local fallback for workspace secrets. " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
   );
 }
 
@@ -208,6 +236,7 @@ export function getSharedSecretEncryptionKey(): Buffer {
 export function hasSharedSecretEncryptionKeyMaterial(): boolean {
   if (typeof process === "undefined") return false;
   return Boolean(
+    workspaceSharedEncryptionKeyMaterial() ||
     process.env.SECRETS_ENCRYPTION_KEY ||
     a2aSharedEncryptionKeyMaterial() ||
     process.env.BETTER_AUTH_SECRET,

package/src/secrets/storage.ts

@@ -2,10 +2,12 @@
  * Storage layer for the framework secrets registry.
  *
  * Values are encrypted at rest with AES-256-GCM. The workspace-shared
- * encryption key is derived from `SECRETS_ENCRYPTION_KEY` (preferred) or the
- * workspace-wide `A2A_SECRET`. `BETTER_AUTH_SECRET` and app-scoped keys remain
- * read fallbacks for rows written before sibling apps converged on the shared
- * key. Successful fallback reads race-safely refresh the shared ciphertext.
+ * encryption key prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy
+ * combined `SECRETS_ENCRYPTION_KEY`, then the workspace-wide `A2A_SECRET`.
+ * A configured previous workspace key, `BETTER_AUTH_SECRET`, and app-scoped
+ * keys remain read fallbacks for rows written before sibling apps converged on
+ * the shared key. Successful fallback reads race-safely refresh the shared
+ * ciphertext.
  *
  * Secret values are NEVER logged and NEVER returned from any route handler.
  */

package/src/server/agent-chat/action-filters-a2a.ts

@@ -360,6 +360,8 @@ export const DELEGATED_AGENT_EXECUTION_CONTRACT = `
 <delegated-agent-contract>
 This request was delegated by another app. You are the specialist owner of the work.
 - Interpret the caller's natural-language objective using your own instructions, skills, data dictionary, credentials, and tools. Choose providers, schemas, queries, and joins here; never ask the caller to invent SQL or source-specific implementation details for you.
+- Finish the objective autonomously in this delegated turn whenever a safe, reasonable default exists. Do not bounce the work back with UI-navigation requests, implementation questions, or intermediate status. Ask for input only when authorization, missing credentials, or a consequential user choice truly blocks progress.
+- When evidence is incomplete, return the best grounded partial answer with explicit coverage gaps instead of refusing or asking the caller to choose your source, filter, dashboard, or workflow.
 - Minimize round trips. Filter, join, aggregate, paginate, stage, and reduce large datasets inside your own tools rather than returning raw records or transcripts.
 - Return a concise caller-ready result with the answer, source and coverage details, relevant counts or IDs, caveats/partial gaps, and exact artifact URLs. Do not return tool transcripts or large raw payloads.
 </delegated-agent-contract>`;

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

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

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

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

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

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.