@agent-native/core 0.131.5 → 0.131.7

package/src/server/agent-chat/plugin-options.ts

@@ -341,6 +341,27 @@ export interface AgentChatPluginOptions {
    */
   externalAgents?: ExternalAgentPolicy;
 
+  /**
+   * Allow this app's A2A agent to delegate to a different app through the
+   * built-in `call-agent` tool. Enabled by default so a receiver keeps the
+   * same cross-app capability as its interactive agent. Set false only for an
+   * intentionally isolated app. Core enforces a bounded delegation path so
+   * cycle safety does not depend on removing the tool.
+   */
+  a2aAgentDelegation?: boolean;
+
+  /**
+   * Resource budget for delegated A2A/MCP agent turns. Defaults are stricter
+   * than interactive chat because every retained tool result is re-sent on
+   * later iterations and delegated callers need a compact answer, not a raw
+   * transcript. Apps may raise one limit deliberately for proven workloads.
+   */
+  delegatedRunPolicy?: {
+    maxIterations?: number;
+    maxRunInputTokens?: number;
+    maxToolResultChars?: number;
+  };
+
   /**
    * Skip mounting the remote MCP protocol route.
    *
@@ -384,5 +405,17 @@ export interface AgentChatPluginOptions {
    * App-level default tool-call limits. Individual actions override these with
    * their own `timeoutMs` / `maxResultChars` declarations.
    */
-  toolLimits?: { timeoutMs?: number; maxResultChars?: number };
+  toolLimits?: {
+    timeoutMs?: number;
+    maxResultChars?: number;
+    /** Absolute cap applied even when an individual action declares more. */
+    hardMaxResultChars?: number;
+  };
+}
+
+/** Cross-app agent delegation is a workspace default; false is an isolation opt-out. */
+export function resolveA2AAgentDelegationEnabled(
+  options?: Pick<AgentChatPluginOptions, "a2aAgentDelegation">,
+): boolean {
+  return options?.a2aAgentDelegation !== false;
 }

package/src/server/agent-chat/prompt-resources.ts

@@ -1094,7 +1094,7 @@ export async function loadResourcesForPrompt(
       // which peer apps exist, so this block is not droppable: without it the
       // agent reports cross-app work as impossible instead of delegating.
       addSection(
-        `<available-apps>\nWorkspace apps available over A2A/call-agent:\n${lines.join("\n")}\n\nUse \`call-agent\` with the app id when another app owns the work or data. Use tool-search or app-specific actions for details only when needed.\n\nThese one-liners are the only cross-app detail in this prompt. Before building a capability another app may already own, before telling the user what is or is not possible across apps, and whenever the user asks which app to use, call \`describe-workspace-apps\` — it reads each peer's live agent card and returns their exact callable actions. Never hand-maintain a list of workspace apps in code or docs; it goes stale silently.\n</available-apps>`,
+        `<available-apps>\nWorkspace apps available over A2A/call-agent:\n${lines.join("\n")}\n\nWhen another app owns the work or data, use \`call-agent\` with the app id and a natural-language message. The receiving specialist owns source selection, schema interpretation, queries, joins, and use of its local tools. Direct action invocation is optional for an exact bounded read with a fully known schema; never use it to compensate for unreliable delegation.\n\nThese one-liners are the only cross-app detail in this prompt. Before building a capability another app may already own, before telling the user what is or is not possible across apps, and whenever the user asks which app to use, call \`describe-workspace-apps\` - it reads each peer's live agent card for current purpose and optional capability details. Never hand-maintain a list of workspace apps in code or docs; it goes stale silently.\n</available-apps>`,
         "required",
       );
     }

package/src/server/agent-chat-plugin.ts

@@ -32,7 +32,6 @@ import {
   sanitizeA2ACorrelationId,
   sanitizeA2ACorrelationMetadata,
 } from "../a2a/correlation.js";
-import { applyAgentTextEventToBuffer } from "../a2a/response-text.js";
 import {
   createA2AApproval,
   updateTaskStatusMessage,
@@ -77,6 +76,7 @@ import {
   abortTurnDurably,
   subscribeToRun,
   type ActionEntry,
+  type AgentLoopOutcome,
 } from "../agent/production-agent.js";
 import {
   callerHasRunAccess,
@@ -97,6 +97,7 @@ import {
   mergeThreadDataForClientSave,
   upsertUserMessage,
 } from "../agent/thread-data-builder.js";
+import { appendThreadDebugHistory } from "../agent/thread-debug-history.js";
 import { attachToolSearch } from "../agent/tool-search.js";
 import type {
   AgentChatAttachment,
@@ -274,6 +275,9 @@ import {
 // ---------------------------------------------------------------------------
 import {
   createA2AEngineToolSurface,
+  DEFAULT_DELEGATED_MAX_ITERATIONS,
+  DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS,
+  DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS,
   filterAgentTools,
   filterPublicAgentActions,
   filterDirectA2AActions,
@@ -306,6 +310,7 @@ import {
   generateCorpusToolsPrompt,
 } from "./agent-chat/framework-prompts.js";
 import {
+  resolveA2AAgentDelegationEnabled,
   type AgentChatPluginOptions,
   type NitroPluginDef,
 } from "./agent-chat/plugin-options.js";
@@ -340,6 +345,11 @@ export type { AgentChatPluginOptions };
 export { runA2AAgentLoop };
 export { runMCPAgentLoop };
 export { createA2AEngineToolSurface };
+export {
+  DEFAULT_DELEGATED_MAX_ITERATIONS,
+  DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS,
+  DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS,
+};
 export { shouldBlockInProductCodeEditingSurface };
 export { loadRunCodeToolEntries };
 export { shouldDisableRecurringJobsRuntime };
@@ -516,6 +526,8 @@ export function createAgentChatPlugin(
         (env === "development" || env === "test") &&
         process.env.AGENT_MODE !== "production";
       const routePath = options?.path ?? "/_agent-native/agent-chat";
+      const a2aAgentDelegationEnabled =
+        resolveA2AAgentDelegationEnabled(options);
 
       // Mutable mode flag — persisted to the `settings` table so a user who
       // toggles to "Production" stays in prod mode across server restarts.
@@ -1623,35 +1635,43 @@ export function createAgentChatPlugin(
           // a day rollover (or the resources/extra content changing) only
           // invalidates the cached prompt prefix as late as possible.
           const runtimeContext = runtimeContextForEvent(context.event);
-          const systemPrompt = devActive
-            ? devPrompt +
-              SYSTEM_PROMPT_CACHE_SPLIT +
-              resources +
-              schemaBlock +
-              extra +
-              modelOverlay +
-              runtimeContext
-            : basePrompt +
-              SYSTEM_PROMPT_CACHE_SPLIT +
-              resources +
-              schemaBlock +
-              extra +
-              modelOverlay +
-              runtimeContext;
+          // Delegated turns use native template actions in every environment,
+          // so they must also receive the native-tool prompt. The interactive
+          // dev prompt teaches `pnpm action` and would send this receiver back
+          // into the shell loop the native action surface exists to prevent.
+          const systemPrompt =
+            basePrompt +
+            SYSTEM_PROMPT_CACHE_SPLIT +
+            resources +
+            schemaBlock +
+            extra +
+            modelOverlay +
+            runtimeContext;
           if (a2aRunContext) a2aRunContext.systemPrompt = systemPrompt;
 
-          // Build tools — same as interactive handler but WITHOUT call-agent
-          // to prevent infinite recursive A2A loops (agent calling itself).
-          // In dev mode, template actions are invoked via bash (not native tools),
-          // so they're omitted from the tool registry — see allScripts comment.
+          // Build tools — same as interactive handler. Cross-app delegation is
+          // enabled by default; call-agent carries a bounded visited-app path
+          // and rejects cycles/excessive hops before dispatch.
+          // Delegated turns keep template actions as NATIVE tools even in dev,
+          // unlike the interactive surface (see the allScripts comment). Dev
+          // routes template actions through bash there to dodge the degenerate
+          // empty-object tool call some models emit for complex schemas — a
+          // person can just retry. A delegated caller cannot: with no native
+          // action the sibling agent shells out, and an A2A turn that misfires
+          // has no one to correct it, so it retries the same command until the
+          // repetition guard kills the run minutes later. A rejected `{}` call
+          // returns a schema error the model can fix on the next step, which is
+          // strictly better than a shell loop nobody can see.
           const a2aActions = attachToolSearch(
             devActive
               ? {
+                  ...templateScripts,
                   ...resourceScripts,
                   ...docsScripts,
                   ...(lazyContext ? frameworkContextTool : {}),
                   ...urlTools,
                   ...chatScripts,
+                  ...(a2aAgentDelegationEnabled ? callAgentScript : {}),
                   ...fetchTool,
                   ...webSearchTool,
                   ...workspaceFilesTool,
@@ -1675,6 +1695,7 @@ export function createAgentChatPlugin(
                   ...(lazyContext ? frameworkContextTool : {}),
                   ...urlTools,
                   ...chatScripts,
+                  ...(a2aAgentDelegationEnabled ? callAgentScript : {}),
                   ...fetchTool,
                   ...webSearchTool,
                   ...workspaceFilesTool,
@@ -1711,6 +1732,7 @@ export function createAgentChatPlugin(
           // event stream so pre-tool narration never leaks as the A2A result.
           const a2aEvents: AgentChatEvent[] = [];
           const a2aToolResults: A2AToolResultSummary[] = [];
+          let a2aOutcome: AgentLoopOutcome | undefined;
           let lastRecoverableArtifactText = "";
           let activityState = createA2AAgentActivityState();
           let lastActivityCheckpointAt = 0;
@@ -1775,8 +1797,16 @@ export function createAgentChatPlugin(
               runId: context.taskId,
               networkProtocol: "a2a",
               networkId: context.taskId,
+              networkPeer: correlation.callerApp,
+              delegationDepth: correlation.delegationDepth ?? 1,
+              visitedApps:
+                correlation.visitedApps ??
+                (correlation.callerApp ? [correlation.callerApp] : []),
               threadId: context.taskId,
               turnId: context.taskId,
+              onOutcome: (outcome) => {
+                a2aOutcome = outcome;
+              },
               send: (event) => {
                 a2aEvents.push(event);
                 const nextActivityState = applyA2AAgentActivityEvent(
@@ -1833,6 +1863,7 @@ export function createAgentChatPlugin(
               signal: controller.signal,
             },
             {
+              delegatedRunPolicy: options?.delegatedRunPolicy,
               finalResponseGuard: options?.finalResponseGuard,
               runSoftTimeoutMs: options?.runSoftTimeoutMs,
             },
@@ -1932,7 +1963,7 @@ export function createAgentChatPlugin(
           const { responseText, finalText } = assembleA2AFinalResponse(
             a2aEvents,
             a2aToolResults,
-            { event: context.event },
+            { event: context.event, outcome: a2aOutcome },
           );
 
           console.log(
@@ -1946,7 +1977,7 @@ export function createAgentChatPlugin(
               buildA2AAgentActivityPart(activityState),
               {
                 type: "text" as const,
-                text: finalText || "(no response)",
+                text: finalText,
               },
             ],
           };
@@ -2046,11 +2077,14 @@ export function createAgentChatPlugin(
             const model = normalizeModelForEngine(mcpEngine, mcpModelCandidate);
 
             // Same actions as A2A — without call-agent to prevent loops.
-            // In dev mode, template actions go through bash, not native tools.
+            // `ask_app` is delegated too, so template actions stay native in dev
+            // here for the same reason as the A2A surface above: an external
+            // caller cannot nurse a shell command that misfires.
             const devActiveMcp = isDevMode();
             const mcpActions = attachToolSearch(
               devActiveMcp
                 ? {
+                    ...templateScripts,
                     ...resourceScripts,
                     ...docsScripts,
                     ...(lazyContext ? frameworkContextTool : {}),
@@ -2106,36 +2140,22 @@ export function createAgentChatPlugin(
             const schemaBlock = lazyContext
               ? ""
               : await buildSchemaBlock(SHARED_OWNER, databaseToolsMode);
-            // Build the MCP handler's own prompt — always use the bash-based
-            // dev prompt in dev mode because mcpActions routes template actions
-            // through bash (`devScriptsForA2A`), regardless of `nativeActionsInDev`.
-            const mcpDevPrompt =
-              (options?.devSystemPrompt
-                ? options.devSystemPrompt +
-                  (options?.systemPrompt ??
-                    (lazyContext
-                      ? PROD_FRAMEWORK_PROMPT_COMPACT
-                      : PROD_FRAMEWORK_PROMPT))
-                : lazyContext
-                  ? DEV_FRAMEWORK_PROMPT_COMPACT
-                  : DEV_FRAMEWORK_PROMPT) + devActionsPrompt;
             // Stable-first ordering: runtime-context (which changes daily)
             // goes last so the cached prompt prefix survives as long as
             // possible — same pattern as the other prompt-assembly sites in
             // this plugin (A2A above, prod/anonymous/dev handlers below).
-            const systemPrompt = devActiveMcp
-              ? mcpDevPrompt +
-                SYSTEM_PROMPT_CACHE_SPLIT +
-                resources +
-                schemaBlock +
-                buildRuntimeContextPrompt()
-              : basePrompt +
-                SYSTEM_PROMPT_CACHE_SPLIT +
-                resources +
-                schemaBlock +
-                buildRuntimeContextPrompt();
+            // ask_app receives native template actions even in dev, so the
+            // native-tool prompt is required here for the same reason as A2A.
+            const systemPrompt =
+              basePrompt +
+              SYSTEM_PROMPT_CACHE_SPLIT +
+              resources +
+              schemaBlock +
+              buildRuntimeContextPrompt();
 
-            let accumulatedText = "";
+            const mcpEvents: AgentChatEvent[] = [];
+            const mcpToolResults: A2AToolResultSummary[] = [];
+            let mcpOutcome: AgentLoopOutcome | undefined;
             const controller = new AbortController();
 
             await runMCPAgentLoop(
@@ -2167,15 +2187,24 @@ export function createAgentChatPlugin(
                 networkId: mcpRunId,
                 threadId: mcpRunId,
                 turnId: mcpRunId,
+                onOutcome: (outcome) => {
+                  mcpOutcome = outcome;
+                },
                 send: (event) => {
-                  accumulatedText = applyAgentTextEventToBuffer(
-                    accumulatedText,
-                    event,
-                  );
+                  mcpEvents.push(event);
+                  if (event.type === "tool_done") {
+                    mcpToolResults.push({
+                      tool: event.tool,
+                      result: event.result,
+                      isError: event.isError,
+                      completedSideEffect: event.completedSideEffect,
+                    });
+                  }
                 },
                 signal: controller.signal,
               },
               {
+                delegatedRunPolicy: options?.delegatedRunPolicy,
                 finalResponseGuard: options?.finalResponseGuard,
                 runSoftTimeoutMs: options?.runSoftTimeoutMs,
               },
@@ -2197,7 +2226,9 @@ export function createAgentChatPlugin(
               },
             );
 
-            return accumulatedText || "(no response)";
+            return assembleA2AFinalResponse(mcpEvents, mcpToolResults, {
+              outcome: mcpOutcome,
+            }).finalText;
           },
         });
       }
@@ -2360,11 +2391,7 @@ export function createAgentChatPlugin(
               engine: runCtx?.engine?.name ?? "unknown",
               timestamp: Date.now(),
             };
-            repo._debug = debug;
-            const debugRuns = Array.isArray(repo._debugRuns)
-              ? repo._debugRuns
-              : [];
-            repo._debugRuns = [...debugRuns, debug].slice(-50);
+            repo = appendThreadDebugHistory(repo, debug);
 
             const meta = extractThreadMeta(repo);
             await updateThreadData(
@@ -4520,6 +4547,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             const body = await readBody(event).catch(() => null);
             const threadId =
               typeof body?.threadId === "string" ? body.threadId : "";
+            const reason =
+              typeof body?.reason === "string" &&
+              /^[a-z0-9_-]{1,64}$/i.test(body.reason)
+                ? body.reason
+                : "user";
             if (
               !/^[a-zA-Z0-9_-]{1,160}$/.test(turnId) ||
               !threadId ||
@@ -4528,7 +4560,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
               setResponseStatus(event, 404);
               return { error: "Run not found" };
             }
-            await markTurnAborted(threadId, turnId);
+            await markTurnAborted(threadId, turnId, reason);
             return { ok: true };
           }
 

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

@@ -223,14 +223,26 @@ 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
-  `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set (for example,
+- Values are encrypted at rest with AES-256-GCM. Generic app-local secrets
+  prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (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.
+  `BETTER_AUTH_SECRET`.
+- 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.
 
 ## Ad-hoc Keys
 

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

@@ -223,14 +223,26 @@ 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
-  `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set (for example,
+- Values are encrypted at rest with AES-256-GCM. Generic app-local secrets
+  prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (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.
+  `BETTER_AUTH_SECRET`.
+- 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.
 
 ## Ad-hoc Keys
 

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

@@ -136,12 +136,19 @@ log or return them.
 ## Advertising what this agent can do
 
 Card `skills` are derived from actions marked `publicAgent`. An app that marks
-none publishes `"skills": []` and peers cannot see what it offers, even though
-delegation still works. Mark the actions a peer should be able to see and
-invoke directly; leave the rest internal.
+none publishes `"skills": []`, but natural-language delegation still works
+because the receiving agent loads its own instructions, skills, data
+dictionary, credentials, and tools. Mark only stable machine contracts that a
+peer may intentionally invoke directly; leave implementation actions internal.
 
 ## Calling another agent
 
+Natural-language delegation is the default for agent-to-agent work. Tell the
+receiving specialist the objective, relevant IDs/date range, and desired result
+shape. The receiver owns source selection, schemas, queries, joins, SQL, and
+provider-specific details. Do not switch to a direct action merely because a
+delegated run is slow or flaky; fix the A2A path instead.
+
 ### Simple: `callAgent()` (text in, text out)
 
 ```ts
@@ -162,10 +169,12 @@ production. `resolveA2ACallerAuth()` pulls the authenticated email, org domain,
 and org secret out of request context; pass them explicitly only from CLI or
 cron, where there is no request.
 
-### Fast bounded read: `invokeAgentAction()`
+### Explicit machine-contract exception: `invokeAgentAction()`
 
-When the caller knows the exact receiver-owned read action and arguments, skip
-the receiver's model loop:
+Use direct invocation only when a trusted integration already specifies the
+exact receiver-owned semantic read action and complete arguments. It is an
+optional machine API, not an agent-performance shortcut or fallback for failed
+message delegation:
 
 ```ts
 import { invokeAgentAction } from "@agent-native/core/a2a";
@@ -184,7 +193,9 @@ The receiver still owns schema validation, credentials, access scoping, audit
 attribution, and exposure policy. Direct invocation is available only for
 cataloged, authenticated, explicitly exposed read-only actions that do not
 require approval. Its JWT is audience-bound to the receiving app. Use normal
-message delegation for planning, synthesis, multi-step work, or mutations.
+message delegation whenever the receiver must interpret the request, choose a
+source, consult its data dictionary, plan, synthesize, join data, or perform a
+multi-step workflow.
 
 Inside an agent loop, `call-agent` exposes the same path with `action` + `input`;
 omit `message` and `taskId` in that mode.

package/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -36,11 +36,11 @@ The main agent should discover available siblings before assuming capability:
   `discoverWorkspaceAgents()`. It carries one line per app — enough to know a
   sibling exists, not enough to know what it can do.
 - Use the built-in `describe-workspace-apps` tool for actual capability.
-  It reads each peer's live `/.well-known/agent-card.json` and returns their
-  callable action names; pass `app: "<id>"` for one peer's full list with
-  descriptions. Call it before building something a sibling may already own,
-  before telling a user what is or is not possible across apps, and whenever
-  someone asks which app to use for a job.
+  It reads each peer's live `/.well-known/agent-card.json` and returns its
+  purpose plus any optional stable machine contracts; pass `app: "<id>"` for
+  one peer's full description. Call it before building something a sibling may
+  already own, before telling a user what is or is not possible across apps,
+  and whenever someone asks which app to use for a job.
 - Never hand-maintain a markdown or code list of what each workspace app does.
   A stale catalog is worse than none: it reads as authoritative while pointing
   at capabilities that moved or vanished. An app's purpose belongs in its own
@@ -49,17 +49,18 @@ The main agent should discover available siblings before assuming capability:
   actions — both of which `describe-workspace-apps` reads live.
 - UI shells, headless surfaces, and scripts can read the same registry through
   `GET /_agent-native/agents?selfAppId=<app-id>`.
-- Code or CLI callers should use the first-class A2A invocation path
-  (`invokeAgent()` / `agent-native invoke`) when they need to call an app by
-  id, name, or URL.
+- Code or CLI callers should use the first-class message-based A2A invocation
+  path (`invokeAgent()` / `agent-native invoke`) when they need to ask an app
+  by id, name, or URL.
 - In the agent loop, use `call-agent` with the sibling app id when another app
   owns the work or data. Never call the current app through `call-agent`; use
   local actions instead.
-- When the exact sibling-owned read action and input are already known, use
-  `invokeAgentAction()` or `call-agent` with `action` + `input`. This preserves
-  the receiver's credentials and access checks while skipping its second model
-  loop. Use prompt-based `invokeAgent()` only when the sibling must reason,
-  synthesize, mutate, or perform a multi-step workflow.
+- Send a natural-language objective by default so the sibling can apply its own
+  instructions, skills, schemas, data dictionary, credentials, and tools.
+  `invokeAgentAction()` or `call-agent` with `action` + `input` is only for an
+  explicit stable semantic read contract whose complete input is already known.
+  Never expose or call an implementation action as a workaround for slow or
+  failed message delegation.
 
 Send narrow prompts to siblings: name the exact question, relevant ids, date
 ranges, and expected output shape. Preserve returned ids and URLs verbatim.
@@ -112,7 +113,7 @@ For a sales-intelligence workspace, split the job into small apps:
 | `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |
 | `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |
 | `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |
-| `deal-brief` | Orchestration and final brief | `invokeAgent()` or `call-agent` to the three apps |
+| `deal-brief` | Orchestration and final brief | message-based `invokeAgent()` or `call-agent` to the three apps |
 
 Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open
 deals, asks `gong-evidence` for recent transcript evidence about those deals,

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

@@ -223,14 +223,26 @@ 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
-  `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set (for example,
+- Values are encrypted at rest with AES-256-GCM. Generic app-local secrets
+  prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (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.
+  `BETTER_AUTH_SECRET`.
+- 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.
 
 ## Ad-hoc Keys
 

package/src/vite/client.ts

@@ -2190,6 +2190,7 @@ function ssrStubPlugin(packages: string[]): Plugin | null {
     "getIsolationScope",
     "init",
     "isChangeOrigin",
+    "isNodeEmpty",
     "mergeAttributes",
     "renderToString",
     "applyUpdate",