@agent-native/core 0.126.0 → 0.127.1

package/corpus/core/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/corpus/core/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>

package/corpus/templates/design/app/hooks/use-question-flow.ts

@@ -3,14 +3,28 @@ import {
   useGuidedQuestionFlow,
   type GuidedQuestionAnswers,
 } from "@agent-native/core/client/agent-chat";
+import { type PromptComposerSubmitOptions } from "@agent-native/core/client/composer";
 import { useCallback } from "react";
 
 import { sendToDesignAgentChat } from "@/lib/agent-chat";
 
+export interface QuestionFlowModelSelection {
+  model?: string;
+  engine?: string;
+  effort?: PromptComposerSubmitOptions["effort"];
+}
+
 interface UseQuestionFlowOptions {
   enabled?: boolean;
   continuationTabId?: string | null;
   onContinue?: (tabId: string) => void;
+  /**
+   * The model this generation started with, read AT SEND TIME. The continuation
+   * is the turn that generates and it opens a fresh thread, which has no
+   * override to inherit. A getter, not a value: the caller's source is a ref
+   * filled after render, so a snapshot taken here would be the pre-kickoff one.
+   */
+  getModelSelection?: () => QuestionFlowModelSelection | null | undefined;
 }
 
 function designQuestionsStateKey(designId: string | undefined): string {
@@ -32,6 +46,7 @@ export function useQuestionFlow(
     enabled = true,
     continuationTabId,
     onContinue,
+    getModelSelection,
   }: UseQuestionFlowOptions = {},
 ) {
   const stateKey = designQuestionsStateKey(designId);
@@ -65,6 +80,8 @@ export function useQuestionFlow(
 
   const sendContinuation = useCallback(
     (message: string, context?: string) => {
+      const selection = getModelSelection?.() ?? {};
+      const { model, engine, effort } = selection;
       // Always request `newTab` (mirroring useAgentGenerating.submit's
       // default). Without it, when there is no continuationTabId yet the
       // message goes to whatever tab is currently active, but the id we
@@ -83,11 +100,14 @@ export function useQuestionFlow(
         submit: true,
         newTab: true,
         ...(continuationTabId ? { tabId: continuationTabId } : {}),
+        ...(model ? { model } : {}),
+        ...(engine ? { engine } : {}),
+        ...(effort ? { effort } : {}),
       });
       onContinue?.(tabId);
       flow.clear();
     },
-    [continuationTabId, flow, onContinue],
+    [continuationTabId, designId, flow, getModelSelection, onContinue],
   );
 
   const handleSubmit = useCallback(

package/corpus/templates/design/changelog/2026-07-28-the-model-you-pick-when-starting-a-new-design-is-now-used-fo.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-28
+---
+
+The model you pick when starting a new design is now used for the design's first generation turn instead of falling back to the default model.

package/corpus/templates/dispatch/changelog/2026-07-28-pending-apps-are-hidden-by-default-and-app-ownership-details.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-28
+---
+
+Pending apps are hidden by default and app ownership details are available from the overflow menu

package/corpus/templates/slides/app/components/editor/EditorSidebar.tsx

@@ -28,7 +28,10 @@ import { toast } from "sonner";
 
 import SlideRenderer from "@/components/deck/SlideRenderer";
 import { GoogleDocImportHint } from "@/components/editor/GoogleDocImportHint";
-import type { UploadedFile } from "@/components/editor/PromptDialog";
+import {
+  isInsidePortaledLayer,
+  type UploadedFile,
+} from "@/components/editor/PromptDialog";
 import {
   Tooltip,
   TooltipContent,
@@ -366,6 +369,7 @@ function AddSlidePopover({
   useEffect(() => {
     if (!open) return;
     const handleClick = (e: MouseEvent) => {
+      if (isInsidePortaledLayer(e.target)) return;
       if (
         panelRef.current &&
         !panelRef.current.contains(e.target as Node) &&

package/corpus/templates/slides/app/components/editor/EditorToolbar.tsx

@@ -64,6 +64,7 @@ import {
   type AspectRatio,
   DEFAULT_ASPECT_RATIO,
 } from "@/lib/aspect-ratios";
+import type { GoogleSlidesExportResult } from "@/lib/export-google-slides-client";
 import { parseUploadResponse } from "@/lib/upload-response";
 import { shortcutLabel } from "@/lib/utils";
 
@@ -134,6 +135,8 @@ interface EditorToolbarProps {
   onExportPdf?: () => void;
   /** Export the deck as PPTX */
   onExportPptx?: () => Promise<void> | void;
+  /** Create the deck in the user's Google Drive as native Google Slides */
+  onExportGoogleSlides?: () => Promise<GoogleSlidesExportResult>;
   /** Active deck aspect ratio (defaults to 16:9 when omitted) */
   aspectRatio?: AspectRatio;
   /** Change the deck's aspect ratio */
@@ -267,6 +270,7 @@ export default function EditorToolbar({
   onDuplicateDeck,
   onExportPdf,
   onExportPptx,
+  onExportGoogleSlides,
   aspectRatio,
   onSetAspectRatio,
   designSystemTitle,
@@ -998,6 +1002,7 @@ graph TD
           onDuplicate={onDuplicateDeck ?? (() => {})}
           onExportPdf={onExportPdf ?? (() => {})}
           onExportPptx={onExportPptx ?? (() => {})}
+          onExportGoogleSlides={onExportGoogleSlides}
         />
       </div>
 

package/corpus/templates/slides/app/components/editor/ExportMenu.tsx

@@ -18,6 +18,11 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
+import type { GoogleSlidesExportResult } from "@/lib/export-google-slides-client";
+
+/** Google Slides' File → Import dialog, primed to ask for a file. */
+const GOOGLE_SLIDES_IMPORT_URL =
+  "https://docs.google.com/presentation/u/0/?usp=import";
 
 interface ExportMenuProps {
   deckId: string;
@@ -25,6 +30,7 @@ interface ExportMenuProps {
   onDuplicate: () => void;
   onExportPdf: () => void;
   onExportPptx: () => Promise<void> | void;
+  onExportGoogleSlides?: () => Promise<GoogleSlidesExportResult>;
   onShareLink?: () => void;
   onShareTeam?: () => void;
 }
@@ -35,6 +41,7 @@ export function ExportMenu({
   onDuplicate,
   onExportPdf,
   onExportPptx,
+  onExportGoogleSlides,
   onShareLink,
   onShareTeam,
 }: ExportMenuProps) {
@@ -84,12 +91,26 @@ export function ExportMenu({
   };
 
   const handleExportGoogleSlides = async () => {
+    if (!onExportGoogleSlides) return;
+    // Opened up-front: browsers only honour window.open() inside the click
+    // gesture, and building the PPTX is async.
+    const target = window.open("", "_blank");
     try {
-      await onExportPptx();
+      const result = await onExportGoogleSlides();
+      if (result.url !== null) {
+        if (target) target.location.href = result.url;
+        toast.success(t("editorExport.googleSlidesCreated"), {
+          description: t("editorExport.googleSlidesCreatedHint"),
+        });
+        return;
+      }
+      console.warn("Google Slides upload unavailable:", result.reason);
+      if (target) target.location.href = GOOGLE_SLIDES_IMPORT_URL;
       toast.success(t("editorExport.googleSlidesDownloaded"), {
         description: t("editorExport.googleSlidesImportHint"),
       });
     } catch (err) {
+      target?.close();
       console.error("Export failed:", err);
       toast.error(t("editorExport.exportFailed"), {
         description:
@@ -166,13 +187,15 @@ export function ExportMenu({
           <IconDownload className="w-4 h-4 mr-2" />
           {t("editorExport.exportPptx")}
         </DropdownMenuItem>
-        <DropdownMenuItem
-          onClick={handleExportGoogleSlides}
-          className="cursor-pointer"
-        >
-          <IconBrandGoogle className="w-4 h-4 mr-2" />
-          {t("editorExport.downloadGoogleSlides")}
-        </DropdownMenuItem>
+        {onExportGoogleSlides && (
+          <DropdownMenuItem
+            onClick={handleExportGoogleSlides}
+            className="cursor-pointer"
+          >
+            <IconBrandGoogle className="w-4 h-4 mr-2" />
+            {t("editorExport.openInGoogleSlides")}
+          </DropdownMenuItem>
+        )}
         <DropdownMenuSeparator />
         <DropdownMenuItem onClick={onDuplicate} className="cursor-pointer">
           <IconCopy className="w-4 h-4 mr-2" />

package/corpus/templates/slides/app/components/editor/PromptDialog.tsx

@@ -16,6 +16,20 @@ export interface UploadedFile {
   size: number;
 }
 
+/**
+ * Radix popovers portal to `document.body`, so a mousedown inside the model
+ * picker or attachment menu reads as "outside" any panel that hosts a composer.
+ * Closing on it unmounts the popover before its own click fires, which looks
+ * exactly like a dead button.
+ */
+export function isInsidePortaledLayer(target: EventTarget | null): boolean {
+  return Boolean(
+    (target as Element | null)?.closest?.(
+      "[data-radix-popper-content-wrapper]",
+    ),
+  );
+}
+
 interface PromptPopoverProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
@@ -98,6 +112,7 @@ export default function PromptPopover({
   useEffect(() => {
     if (!open) return;
     const handleClick = (e: MouseEvent) => {
+      if (isInsidePortaledLayer(e.target)) return;
       if (
         panelRef.current &&
         !panelRef.current.contains(e.target as Node) &&