@agent-native/core 0.125.0 → 0.127.1

package/src/server/email-template.ts

@@ -36,6 +36,12 @@ export interface RenderEmailArgs {
   paragraphs: string[];
   /** Primary call-to-action rendered as a real button. */
   cta?: EmailCta;
+  /**
+   * Optional trusted HTML injected above the CTA — e.g. a template-owned video
+   * thumbnail with a play badge. Injected verbatim, so only pass markup built
+   * by app/template code (never raw user input), and escape any dynamic values.
+   */
+  heroHtml?: string;
   /** Small muted text under the CTA (e.g. expiry note). */
   footer?: string;
   /** Optional app name shown beside the framework logo. */
@@ -108,6 +114,12 @@ export function renderEmail(args: RenderEmailArgs): RenderedEmail {
   const ctaFg = brand ? "#ffffff" : "#0a0a0c";
   const linkColor = brand ?? "#a1a1aa";
 
+  // Trusted markup supplied by the caller (template code, not user input),
+  // injected as-is so a template can own app-specific previews (e.g. a video
+  // thumbnail with a play badge). Callers are responsible for escaping any
+  // dynamic values they interpolate.
+  const heroHtml = args.heroHtml ?? "";
+
   const paragraphsHtml = args.paragraphs
     .map(
       (p) =>
@@ -174,6 +186,7 @@ export function renderEmail(args: RenderEmailArgs): RenderedEmail {
                   ${escapeHtml(args.heading)}
                 </h1>
                 ${paragraphsHtml}
+                ${heroHtml}
                 ${ctaHtml}
                 ${footerHtml}
               </td>

package/src/server/email.ts

@@ -30,6 +30,13 @@ export interface SendEmailArgs {
   html: string;
   text?: string;
   from?: string;
+  /**
+   * Display-name-only override. Keeps the configured (domain-verified) sending
+   * address and just changes the name shown to the recipient, e.g.
+   * "Alice via Clips". Ignored when `from` is set. Prefer this over `from` for
+   * per-user senders: putting a user's own address in `From` breaks SPF/DKIM.
+   */
+  fromName?: string;
   cc?: string | string[];
   replyTo?: string;
   inReplyTo?: string;
@@ -110,9 +117,14 @@ export async function getEmailProvider(): Promise<EmailProvider> {
 function getFromAddress(
   config: EmailTransportConfig,
   override?: string,
+  fromName?: string,
 ): string {
-  const explicit = override || config.from;
-  if (explicit) return explicit;
+  if (override) return override;
+  const base = config.from ?? defaultFromAddress(config);
+  return fromName ? withDisplayName(base, fromName) : base;
+}
+
+function defaultFromAddress(config: EmailTransportConfig): string {
   // Resend lets unverified accounts send from its sandbox domain; SendGrid
   // does not, so falling back there would cause silent 403s at runtime.
   if (config.provider === "sendgrid") {
@@ -123,6 +135,21 @@ function getFromAddress(
   return "Agent Native <onboarding@resend.dev>";
 }
 
+/**
+ * Swap the display name while keeping the verified address. The name is
+ * sanitized and quoted because it lands in a header: CR/LF would allow header
+ * injection, and quotes/angle brackets would break address parsing.
+ */
+function withDisplayName(from: string, name: string): string {
+  const safe = name
+    .replace(/[\r\n"<>\\]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!safe) return from;
+  const address = from.match(/<([^>]+)>/)?.[1]?.trim() ?? from.trim();
+  return `"${safe}" <${address}>`;
+}
+
 async function sendEmailWithSignal(
   args: SendEmailArgs,
   signal?: AbortSignal,
@@ -130,7 +157,7 @@ async function sendEmailWithSignal(
   const config = await resolveEmailTransport();
   signal?.throwIfAborted();
   const provider = config.provider;
-  const from = getFromAddress(config, args.from);
+  const from = getFromAddress(config, args.from, args.fromName);
   const attachments = resolveAttachments(args);
 
   if (provider === "resend") {
@@ -270,10 +297,19 @@ export async function sendEmail(args: SendEmailArgs): Promise<void> {
 
 function parseSendGridFrom(from: string): { email: string; name?: string } {
   const m = from.match(/^\s*(.*?)\s*<(.+)>\s*$/);
-  if (m && m[2]) return { name: m[1] || undefined, email: m[2] };
+  if (m && m[2]) return { name: unquoteDisplayName(m[1]), email: m[2] };
   return { email: from.trim() };
 }
 
+function unquoteDisplayName(name: string): string | undefined {
+  const trimmed = name.trim();
+  const unquoted =
+    trimmed.startsWith('"') && trimmed.endsWith('"')
+      ? trimmed.slice(1, -1).replace(/\\(.)/g, "$1")
+      : trimmed;
+  return unquoted || undefined;
+}
+
 function stripHtml(html: string): string {
   return html
     .replace(/<br\s*\/?>/gi, "\n")

package/src/shared/mcp-embed-headers.ts

@@ -134,9 +134,13 @@ export function shouldAllowMcpEmbedCredentials(
   );
 }
 
+// These paths are served straight off the CDN, so the security-headers h3
+// middleware never runs for them — anything it sets that must also hold for
+// static assets has to be repeated here.
 export const MCP_EMBED_STATIC_ASSET_HEADERS = {
   "Access-Control-Allow-Origin": "*",
   "Cross-Origin-Resource-Policy": "cross-origin",
+  "X-Content-Type-Options": "nosniff",
 } as const;
 
 const STATIC_ASSET_PATTERNS = [

package/src/sharing/actions/share-resource.ts

@@ -8,6 +8,7 @@ import { renderEmail, emailStrong } from "../../server/email-template.js";
 import { sendEmail, isEmailConfigured } from "../../server/email.js";
 import { invalidateCollabAccessCache } from "../../server/poll.js";
 import { getRequestUserEmail } from "../../server/request-context.js";
+import { getUserProfile } from "../../user-profile/store.js";
 import { assertAccess, ForbiddenError } from "../access.js";
 import { requireShareableResource } from "../registry.js";
 import {
@@ -298,10 +299,9 @@ export default defineAction({
         const appName =
           process.env.APP_NAME || process.env.VITE_APP_NAME || "Agent Native";
         let brandLogoUrl: string | undefined;
-        if (reg.getShareEmailLogoUrl) {
+        if (reg.getLogoUrl) {
           try {
-            brandLogoUrl =
-              (await reg.getShareEmailLogoUrl(resource)) ?? undefined;
+            brandLogoUrl = (await reg.getLogoUrl(resource)) ?? undefined;
           } catch (err) {
             console.error(
               "[share-resource] brand logo resolver failed; using default logo:",
@@ -309,9 +309,51 @@ export default defineAction({
             );
           }
         }
+        let brandName = appName;
+        if (reg.getBrandName) {
+          try {
+            brandName = (await reg.getBrandName(resource))?.trim() || appName;
+          } catch (err) {
+            console.error(
+              "[share-resource] brand name resolver failed; using app name:",
+              err,
+            );
+          }
+        }
+        let fromName: string | undefined;
+        let replyTo: string | undefined;
+        if (reg.getSender) {
+          try {
+            const sender = await reg.getSender(resource, {
+              sender: await getUserProfile(actor),
+            });
+            fromName = sender?.fromName?.trim() || undefined;
+            replyTo = sender?.replyTo?.trim() || undefined;
+          } catch (err) {
+            console.error(
+              "[share-resource] sender resolver failed; using default sender:",
+              err,
+            );
+          }
+        }
+        let heroHtml: string | undefined;
+        if (reg.getHeroHtml) {
+          try {
+            heroHtml =
+              (await reg.getHeroHtml(resource, {
+                href: notificationUrl,
+                alt: resourceTitle,
+              })) ?? undefined;
+          } catch (err) {
+            console.error(
+              "[share-resource] hero html resolver failed; omitting preview:",
+              err,
+            );
+          }
+        }
         const subject = `${actor} shared "${resourceTitle}" with you on ${appName}`;
         const { html, text } = renderEmail({
-          brandName: appName,
+          brandName,
           brandLogoUrl,
           preheader: subject,
           heading: "You've been given access",
@@ -319,10 +361,18 @@ export default defineAction({
             `${emailStrong(actor)} has shared the ${reg.displayName} ${emailStrong(resourceTitle)} with you as a ${emailStrong(args.role)}.`,
             `Use the button below to open it. If prompted, sign in with ${emailStrong(principalId)}.`,
           ],
+          heroHtml,
           cta: { label: `Open ${reg.displayName}`, url: notificationUrl },
           footer: `You received this because ${actor} granted you ${args.role} access.`,
         });
-        await sendEmail({ to: principalId, subject, html, text });
+        await sendEmail({
+          to: principalId,
+          subject,
+          html,
+          text,
+          fromName,
+          replyTo,
+        });
       } catch (err) {
         console.error(
           "[share-resource] failed to send share notification:",

package/src/sharing/registry.ts

@@ -17,6 +17,8 @@
  *   });
  */
 
+import type { UserProfile } from "../user-profile/shared.js";
+
 export interface ShareableResourceRegistration {
   /** Stable identifier used across actions, UI, and analytics. e.g. "document". */
   type: string;
@@ -42,8 +44,46 @@ export interface ShareableResourceRegistration {
    * (e.g. the sharing org's own logo), or undefined to fall back. Receives the
    * resource row being shared so the template can scope the logo to its org.
    */
-  getShareEmailLogoUrl?: (
+  getLogoUrl?: (
+    resource: any,
+  ) => string | undefined | Promise<string | undefined>;
+  /**
+   * Optional resolver for the brand name shown beside the logo in the
+   * share-notification email header. Return a display name (e.g. the sharing
+   * org's name) to override the app name, or undefined to keep the default.
+   * Receives the resource row being shared.
+   */
+  getBrandName?: (
+    resource: any,
+  ) => string | undefined | Promise<string | undefined>;
+  /**
+   * Optional resolver for who the share-notification email appears to come
+   * from. `fromName` changes only the display name and keeps the configured,
+   * domain-verified sending address (e.g. "Alice via Clips"); `replyTo` routes
+   * replies to the sharer. `ctx.sender` is the account doing the sharing, so the
+   * template decides how to present them (name, email, avatar).
+   *
+   * Do not put a user's address in the sending address itself — SPF/DKIM sign
+   * the app's domain, so recipients would bounce or spam-filter it.
+   */
+  getSender?: (
+    resource: any,
+    ctx: { sender: UserProfile },
+  ) =>
+    | { fromName?: string; replyTo?: string }
+    | undefined
+    | Promise<{ fromName?: string; replyTo?: string } | undefined>;
+  /**
+   * Optional resolver for a preview block shown above the CTA in the
+   * share-notification email — e.g. a recording thumbnail with a play badge.
+   * Return trusted HTML (built by template code, dynamic values escaped) that
+   * is injected verbatim, or undefined to omit it. `ctx.href` is the resolved
+   * link to the resource; `ctx.alt` is its title. The template owns the entire
+   * preview markup so the generic share action stays app-agnostic.
+   */
+  getHeroHtml?: (
     resource: any,
+    ctx: { href: string; alt?: string },
   ) => string | undefined | Promise<string | undefined>;
   /**
    * Drizzle DB accessor from the template's server/db/index.ts. Required —

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

@@ -1,9 +1,9 @@
 ---
 name: a2a-protocol
 description: >-
-  How agents call other agents via the A2A (agent-to-agent) JSON-RPC protocol.
-  Use when enabling inter-agent communication, exposing agent skills to other
-  agents, or calling external agents from scripts.
+  How agent-native apps discover, authenticate with, and call each other over
+  A2A. Use when connecting one app to another, debugging a remote agent that
+  won't authenticate, exposing skills to peers, or calling agents from scripts.
 scope: dev
 metadata:
   internal: true
@@ -13,110 +13,155 @@ metadata:
 
 ## Rule
 
-Agents can call other agents using the A2A protocol. This is a JSON-RPC-based protocol for agent discovery and communication. Use it when work should go to a different agent entirely — not the local agent chat.
+Agents call other agents over A2A, a JSON-RPC protocol for discovery and
+delegation. Use it when work belongs to a different agent entirely — not the
+local agent chat.
 
-## Why
+Connecting app A to app B is two independent things, and both must be true:
 
-Agent-native apps don't exist in isolation. A mail agent might need analytics data. A calendar agent might need to search issues. A2A lets agents discover each other, send messages, and receive structured results — all over HTTP with bearer token auth.
+1. **B is registered on A** as a `remote-agents/<id>.json` resource.
+2. **A and B share a secret**, so A's signed JWT verifies on B.
 
-## How to Enable A2A (Server Side)
+Neither is a code change, and neither is symmetric. Registering B on A does not
+let B call A.
 
-Add `mountA2A()` to a server plugin:
+## A2A is already mounted
 
-```ts
-// server/plugins/a2a.ts
-import { mountA2A } from "@agent-native/core/a2a";
-
-export default defineNitroPlugin((nitro) => {
-  const app = nitro.h3App;
-
-  mountA2A(app, {
-    name: "Analytics Agent",
-    description: "Queries analytics data across providers",
-    version: "1.0.0",
-    skills: [
-      {
-        id: "query-data",
-        name: "Query Data",
-        description: "Run analytics queries across connected data sources",
-        tags: ["analytics", "data"],
-        examples: ["What were last week's signups?", "Show conversion rates"],
-      },
-    ],
-    apiKeyEnv: "A2A_API_KEY", // env var holding the bearer token
-    streaming: true,          // enable message/stream method
-  });
-});
-```
-
-This mounts the agent-native A2A endpoints:
-
-- `GET /.well-known/agent-card.json` — public agent discovery (no auth required)
-- `POST /_agent-native/a2a` — primary JSON-RPC endpoint (bearer token auth required)
+`createAgentChatPlugin` calls `mountA2A` for every app, so a generated app
+already serves:
 
-The client may fall back to `POST /a2a` for external or legacy peers that only
-expose that simple path. New agent-native apps should document and call the
-`/_agent-native/a2a` endpoint.
+- `GET /.well-known/agent-card.json` — public discovery, never authenticated
+- `POST /_agent-native/a2a` — JSON-RPC, authenticated
 
-## The Config Object
-
-```ts
-interface A2AConfig {
-  name: string;           // agent display name
-  description: string;    // what this agent does
-  version?: string;       // semver version (default: "1.0.0")
-  skills: AgentSkill[];   // capabilities this agent exposes
-  handler?: A2AHandler;   // custom message handler
-  apiKeyEnv?: string;     // env var name for bearer token auth
-  streaming?: boolean;    // enable streaming responses
-}
+Do not add a `mountA2A` server plugin to enable A2A; it is on. Hand-mounting is
+only for a bespoke card or a custom handler (see **Custom mount** below).
 
-interface AgentSkill {
-  id: string;             // unique skill identifier
-  name: string;           // human-readable name
-  description: string;    // what this skill does
-  tags?: string[];        // categorization tags
-  examples?: string[];    // example prompts
-}
-```
+The client falls back to `POST /a2a` for external peers that only expose that
+path. New agent-native apps should call `/_agent-native/a2a`.
 
-## Agent Card
+## Registering a remote agent
 
-The agent card is auto-generated at `GET /.well-known/agent-card.json`. Other agents fetch this to discover what skills are available:
+A remote agent is **a row in the resources table, not a file on disk**. Path
+`remote-agents/<id>.json`, owner `SHARED_OWNER`, content:
 
 ```json
 {
-  "name": "Analytics Agent",
+  "id": "analytics",
+  "name": "Analytics",
   "description": "Queries analytics data across providers",
   "url": "https://analytics.example.com",
-  "version": "1.0.0",
-  "protocolVersion": "0.3",
-  "capabilities": { "streaming": true },
-  "skills": [
-    {
-      "id": "query-data",
-      "name": "Query Data",
-      "description": "Run analytics queries across connected data sources"
-    }
-  ]
+  "color": "#6B7280"
 }
 ```
 
-## Calling Another Agent
+`url` is the only required field. `parseRemoteAgentManifest` accepts **only**
+these five keys — there is no `apiKey`, `env`, `skills`, or `token` field, and
+anything else is silently dropped.
+
+Four ways to create it, all writing the same row:
+
+| Surface | Where |
+| --- | --- |
+| Settings → Manage agent → Connected Agents (A2A) | any app with the settings panel |
+| Agent page → Connections | apps mounting `AgentTabsPage` |
+| Dispatch → Agents → Add external agent | workspace dispatch |
+| The agent itself | `resources` tool, `action: "write"`, `--scope shared` |
+
+The last one matters for template apps with no Code tab: "connect me to
+https://analytics.example.com" is a complete instruction. `remote-agents/` is
+whitelisted as a durable control path, so the write is workspace-scoped, and it
+takes effect on the next `discoverAgents()` call with no restart.
+
+First-party templates are seeded automatically and overlaid on top of manifests,
+so `Mail`, `Calendar`, and friends appear without registration. In dev they
+resolve to `http://localhost:<devPort>`; a manifest pointing at localhost is
+ignored in production.
+
+`call-agent` also accepts a raw URL, which skips registration entirely — useful
+for one-off calls, useless for @-mentions.
+
+### Checking a peer
+
+`GET /_agent-native/agents/probe?url=<base>` reads the peer's card and makes one
+authenticated no-op call, returning `reachable` and `authorized` as independent
+fields. Omit `url` to probe every registered peer. Reachable-but-unauthorized is
+the failure worth looking for: local dev runs the receiver unauthenticated, so a
+mismatched secret only surfaces after deploy. The Connected Agents settings
+section calls this on add and on open.
+
+## Authentication
+
+A2A authenticates with a **short-lived JWT the caller signs**, not a stored
+bearer key. `Authorization: Bearer <jwt>`; claims carry the caller's email and
+org domain; HS256; 15-minute default TTL. There is no per-peer API key
+anywhere in the system, which is why the manifest has no field for one.
+
+Two secrets can sign it:
+
+| Secret | Scope | How it is set |
+| --- | --- | --- |
+| `A2A_SECRET` | whole deployment | env var, **never auto-generated** |
+| org `a2a_secret` | one organization | auto-generated on org creation; Team page UI |
+
+The org secret is the managed path: **Team page → A2A secret** (owner only)
+reveals, copies, regenerates, and pushes it to every discovered peer. Rotation
+is tolerated — the caller tries both secrets in order and sticks to whichever
+worked.
+
+`A2A_SECRET` is the deploy-level path. `workspace-deploy` refuses a production
+workspace deploy without it and prints the generator command. Peers that must
+trust each other need the *same* value on both sides.
+
+With no secret configured at all:
+
+| Runtime | Result |
+| --- | --- |
+| local dev | open, one-time console warning |
+| production | `503` — "A2A authentication not configured" |
+| production, secret set, bad/absent token | `401` |
+
+"Production" is detected broadly (NODE_ENV, Netlify, Lambda, Vercel, Render,
+Fly, Cloud Run, …) and unrecognized deployed hosts fail closed unless the
+request is genuine loopback or `A2A_ALLOW_UNSIGNED_INTERNAL=1`.
+
+`A2AConfig.apiKeyEnv` still exists for static bearer auth against non-agent-native
+peers, but the framework's own mount never sets it. Do not reach for it when
+debugging a connection between two agent-native apps — the answer there is
+always the shared secret.
+
+Never hardcode either secret in source, docs, prompts, app state, action
+descriptions, client bundles, or examples. Read them from runtime config; never
+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.
+
+## Calling another agent
 
 ### Simple: `callAgent()` (text in, text out)
 
 ```ts
-import { callAgent } from "@agent-native/core/a2a";
+import { callAgent, resolveA2ACallerAuth } from "@agent-native/core/a2a";
 
+const auth = await resolveA2ACallerAuth();
 const answer = await callAgent(
   "https://analytics.example.com",
   "What were last week's signups?",
-  { apiKey: process.env.ANALYTICS_A2A_KEY },
+  auth,
 );
 // answer is a plain string
 ```
 
+`callAgent` signs nothing on its own — with no `userEmail`/`orgSecret` in opts
+it calls **unauthenticated**, which silently works in local dev and 401s in
+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()`
 
 When the caller knows the exact receiver-owned read action and arguments, skip
@@ -168,12 +213,13 @@ action arguments or results.
 ### Advanced: `A2AClient` (full control)
 
 ```ts
-import { A2AClient } from "@agent-native/core/a2a";
+import { A2AClient, resolveA2ACallerAuth } from "@agent-native/core/a2a";
 
-const client = new A2AClient(
-  "https://analytics.example.com",
-  process.env.ANALYTICS_A2A_KEY,
-);
+// The second argument is the bearer token itself, not a signing secret.
+const { apiKey, apiKeyFallbacks } = await resolveA2ACallerAuth();
+const client = new A2AClient("https://analytics.example.com", apiKey, {
+  fallbackApiKeys: apiKeyFallbacks,
+});
 
 // Discover agent capabilities
 const card = await client.getAgentCard();
@@ -264,19 +310,6 @@ submitted → working → completed
 - **canceled** — task was canceled via `tasks/cancel`
 - **input-required** — agent needs more information from the caller
 
-## Security
-
-A2A uses bearer token auth. The server reads the token from the environment variable specified by `apiKeyEnv`:
-
-- Set `A2A_API_KEY=<A2A_API_KEY_VALUE>` in the server's deployment environment
-- Callers pass it as `Authorization: Bearer <A2A_API_KEY_VALUE>`
-- The agent card endpoint (`/.well-known/agent-card.json`) is public — no auth needed for discovery
-
-Never hardcode the bearer token in source, docs, prompts, app state, action
-descriptions, client bundles, or examples. A2A tokens are deploy-level secrets
-unless a specific app designs a scoped credential flow; read them from secure
-runtime configuration and never log or return them.
-
 ## Message Parts
 
 Messages contain typed parts:
@@ -287,34 +320,38 @@ Messages contain typed parts:
 | `file`    | `{ type: "file", file: { ... } }`   | Files (bytes or URI)       |
 | `data`    | `{ type: "data", data: { ... } }`   | Structured JSON data       |
 
-## Example: Cross-Agent Workflow
+## Custom mount
 
-A mail agent calls an analytics agent to include data in an email draft:
+Only when the default card is wrong for the app — a curated skill list, a
+non-agent handler, or static bearer auth against an external peer:
 
 ```ts
-// actions/draft-with-analytics.ts
-import { callAgent } from "@agent-native/core/a2a";
-import { writeAppState } from "@agent-native/core/application-state";
-
-export default async function (args: string[]) {
-  // Ask the analytics agent for data
-  const stats = await callAgent(
-    process.env.ANALYTICS_AGENT_URL!,
-    "Summarize last week's key metrics in 3 bullet points",
-    { apiKey: process.env.ANALYTICS_A2A_KEY },
-  );
-
-  // Create a draft with the analytics data
-  await writeAppState("compose-analytics-report", {
-    id: "analytics-report",
-    to: "team@example.com",
-    subject: "Weekly Analytics Summary",
-    body: `Hi team,\n\nHere are last week's numbers:\n\n${stats}\n\nBest`,
-    mode: "compose",
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  mountA2A(nitro, {
+    appId: "analytics",
+    name: "Analytics Agent",
+    description: "Queries analytics data across providers",
+    skills: [
+      {
+        id: "query-data",
+        name: "Query Data",
+        description: "Run analytics queries across connected data sources",
+        tags: ["analytics", "data"],
+        examples: ["What were last week's signups?", "Show conversion rates"],
+      },
+    ],
+    streaming: true,
   });
-}
+});
 ```
 
+Config also carries `handler`, `publicSkillsOnly`, `durableBackgroundRuns`,
+`executeReadOnlyAction`, `executeApproval`, and `apiKeyEnv`. See `A2AConfig` in
+`@agent-native/core/a2a` for the full shape.
+
 ## All Types
 
 All types are exported from `@agent-native/core/a2a`:
@@ -345,5 +382,8 @@ import type {
 ## Related Skills
 
 - **delegate-to-agent** — For work the local agent handles. Use A2A when the work goes to a different agent.
-- **actions** — A2A calls typically happen inside actions
-- **storing-data** — Results from A2A calls are stored in SQL like any other data
+- **authentication** — Org creation, membership, and where the org secret lives.
+- **actions** — A2A calls typically happen inside actions; `publicAgent` marks what peers can see.
+- **storing-data** — Results from A2A calls are stored in SQL like any other data.
+</content>
+</invoke>