@agent-native/core 0.126.0 → 0.127.1

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/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>