@agent-native/core 0.126.0 → 0.127.3

package/corpus/core/src/server/core-routes-plugin.ts

@@ -1569,6 +1569,73 @@ export function createCoreRoutesPlugin(
       // middleware any plugin's route can possibly land behind, regardless of
       // plugin init ordering.
 
+      // Peer reachability + auth probe for the settings UI. Deliberately
+      // separate from `${P}/agents` (discovery) — this route makes live
+      // network calls to the peer, so it is session-gated and answers one
+      // peer (`?url=`) or every registered peer (no query) via `discoverAgents`.
+      //
+      // MUST be mounted BEFORE `${P}/agents` below: h3's `.use()` matches by
+      // path prefix, and that handler always returns a value (never calls
+      // `next()`), so it would swallow `/agents/probe` requests before they
+      // ever reached this route if registered second (same hazard as the A2A
+      // `_process-task` route vs. its `/a2a` catch-all — see a2a/server.ts).
+      getH3App(nitroApp).use(
+        `${P}/agents/probe`,
+        defineEventHandler(async (event) => {
+          if (getMethod(event) !== "GET") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+          }
+          const session = await getSession(event).catch(() => null);
+          if (!session?.email) {
+            setResponseStatus(event, 401);
+            return { error: "Authentication required" };
+          }
+
+          return runWithRequestContext(
+            { userEmail: session.email, orgId: session.orgId ?? undefined },
+            async () => {
+              const { probePeerAgent, probeAllPeerAgents } =
+                await import("./agent-peer-probe.js");
+              const query = getRequestURL(event).searchParams;
+              const urlParam = query.get("url");
+
+              if (urlParam === null) {
+                const selfAppId = query.get("selfAppId") ?? undefined;
+                const { discoverAgents } = await import("./agent-discovery.js");
+                const agents = await discoverAgents(selfAppId);
+                const results = await probeAllPeerAgents(agents);
+                return { results };
+              }
+
+              if (!urlParam.trim()) {
+                setResponseStatus(event, 400);
+                return { error: "url is required" };
+              }
+
+              const result = await probePeerAgent({
+                id: "probe",
+                name: urlParam,
+                description: "",
+                url: urlParam,
+                color: "",
+              });
+
+              // Reachability and auth are independent, but a malformed/SSRF-blocked
+              // URL is a caller input error, not a peer that failed to answer — the
+              // one case where the probe's "unreachable" result is reclassified into
+              // a 400 instead of a 200 with `reachable: false`.
+              if (result.error?.startsWith("SSRF blocked:")) {
+                setResponseStatus(event, 400);
+                return { url: urlParam, error: result.error };
+              }
+
+              return result;
+            },
+          );
+        }),
+      );
+
       // Agent discovery primitive — shared by headless CLI/A2A surfaces and
       // UI shells that need to show connected peer apps without depending on
       // the chat route namespace.

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

@@ -9,8 +9,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

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

@@ -9,8 +9,10 @@ npm-debug.log*
 pnpm-debug.log*
 
 node_modules
+build/
 dist
 dist-ssr
+.output/
 *.local
 
 # Editor directories and files

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -377,6 +377,29 @@ view only when the user asked to focus one specific screen.
 
 ## HTML Structure Requirements
 
+### The save gate rejects malformed markup
+
+Every path that persists model-authored HTML — `generate-design`, `create-file`,
+`present-design-variants`, `edit-design`, `update-file`, canvas edits — runs an
+integrity check, and a **new** file is held to it strictly. Import paths
+(Figma, localhost, templates, duplication) deliberately do not fail closed:
+that markup comes from a real app or an existing design, and rejecting it would
+block bringing work in rather than prevent a bad generation.
+Rejections name the file, line, column, and offending source line — fix exactly
+what it points at instead of re-sending the payload differently. Blocked: an
+attribute quote that is never closed; an unclosed element or a closing tag with
+no opener; content ending mid-tag (a payload cut off in transit); a
+`<style>`/`<script>` missing its opener or closer; duplicated editor-managed
+style blocks; more than one `<html>`/`<body>`.
+
+This exists because the HTML parser never throws — it recovers silently and
+renders a page, just not the one you wrote. An unterminated quote in `<head>`
+swallows every following tag into that attribute, so the Tailwind runtime stops
+applying and the screen renders unstyled with no console error to show it.
+
+Saves may also return non-blocking `warnings` (e.g. utility classes with no
+reachable Tailwind runtime). Fix those before reporting the design as ready.
+
 ### Mandatory Elements
 
 Every `index.html` must include:

package/corpus/templates/design/actions/create-file.ts

@@ -6,6 +6,10 @@ import { nanoid } from "nanoid";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import {
+  assertDesignHtmlCreateIntegrity,
+  describeDesignHtmlIntegrityIssue,
+} from "../shared/html-integrity.js";
 import { annotateScreenHtmlForPersist } from "../shared/screen-annotation.js";
 
 export default defineAction({
@@ -63,6 +67,14 @@ export default defineAction({
     // the first time someone opens it.
     const annotatedContent = annotateScreenHtmlForPersist(content, fileType);
 
+    // Reject malformed HTML before the row exists — creation went through raw
+    // inserts, so it was the one write path with no integrity gate.
+    const advisory = assertDesignHtmlCreateIntegrity({
+      content: annotatedContent,
+      fileType: fileType ?? "html",
+      filename,
+    });
+
     await db.insert(schema.designFiles).values({
       id,
       designId,
@@ -94,6 +106,9 @@ export default defineAction({
       fileType: resolvedFileType,
       renderable,
       urlPath: renderable ? `/design/${designId}` : null,
+      ...(advisory.length > 0
+        ? { warnings: advisory.map(describeDesignHtmlIntegrityIssue) }
+        : {}),
     };
   },
 });

package/corpus/templates/design/actions/generate-design.ts

@@ -45,6 +45,11 @@ import {
   type DesignGenerationSession,
   updateGenerationSessionWithSavedFiles,
 } from "../shared/generation-session.js";
+import {
+  assertDesignHtmlCreateIntegrity,
+  describeDesignHtmlIntegrityIssue,
+  inspectDesignHtmlDocumentIntegrity,
+} from "../shared/html-integrity.js";
 import { assertLockedLayersPreserved } from "../shared/locked-layers.js";
 import { widthToPrefix } from "../shared/responsive-classes.js";
 import { annotateScreenHtmlForPersist } from "../shared/screen-annotation.js";
@@ -769,6 +774,38 @@ const generateDesignAction = defineAction({
       content: annotateScreenHtmlForPersist(file.content, file.fileType),
     }));
 
+    // Gate every NEW file up front so a rejected file cannot orphan the ones
+    // written before it. Existing files take the edit transition inside
+    // writeInlineSourceFile, which still allows repairing a malformed screen.
+    const integrityWarnings: Array<{ filename: string; message: string }> = [];
+    for (const file of annotatedFiles) {
+      if ((file.fileType ?? "html") !== "html") continue;
+      const existing = existingByName.get(file.filename);
+      // A row changing type into HTML is new HTML, not an edit: the edit
+      // transition validates against the row's CURRENT type, so a css→html
+      // candidate would skip the HTML checks and still be stored as HTML below.
+      const becomesHtml =
+        existing !== undefined && (existing.fileType ?? "html") !== "html";
+      // Blocking applies to new files and type transitions. An existing HTML row
+      // takes the lenient edit transition instead, so a legacy-malformed screen
+      // stays repairable — but its advisories are still reported, or the same
+      // content would warn as a new file and save silently as a regeneration.
+      const advisory =
+        !existing || becomesHtml
+          ? assertDesignHtmlCreateIntegrity({
+              content: file.content,
+              fileType: "html",
+              filename: file.filename,
+            })
+          : (inspectDesignHtmlDocumentIntegrity(file.content).advisory ?? []);
+      for (const entry of advisory) {
+        integrityWarnings.push({
+          filename: file.filename,
+          message: describeDesignHtmlIntegrityIssue(entry),
+        });
+      }
+    }
+
     for (const file of annotatedFiles) {
       const existing = existingByName.get(file.filename);
       if (existing) {
@@ -1198,6 +1235,9 @@ const generateDesignAction = defineAction({
       savedFiles,
       placedFrames,
       fileCount: savedFiles.length,
+      // Non-blocking: a well-formed screen with no Tailwind runtime renders
+      // unstyled, which reads as a layout bug rather than a missing runtime.
+      ...(integrityWarnings.length > 0 ? { warnings: integrityWarnings } : {}),
       ...creativeContextProvenance,
     };
   },

package/corpus/templates/design/actions/present-design-variants.ts

@@ -19,6 +19,7 @@ import {
   type CanvasFramePlacement,
 } from "../shared/canvas-frames.js";
 import { isUniqueConstraintViolation } from "../shared/db-conflict.js";
+import { assertDesignHtmlWellFormed } from "../shared/html-integrity.js";
 import { widthToPrefix } from "../shared/responsive-classes.js";
 import { annotateScreenHtmlForPersist } from "../shared/screen-annotation.js";
 
@@ -826,6 +827,21 @@ export default defineAction({
   run: async ({ designId, prompt, variants, deleteSupersededSetIds }) => {
     await assertAccess("design", designId, "editor");
 
+    // Before any mutation. These are model-authored screens created by raw
+    // insert, so they need the same well-formedness gate as generate-design —
+    // though not its document-shape rules, since a variant may be a sketch with
+    // `<html>`/`<body>` implied. Ordering is the load-bearing part: the
+    // supersession and deletion below are irreversible, so throwing after them
+    // would destroy existing variant sets and create nothing to replace them.
+    for (const variant of variants) {
+      const candidate = variant.content?.trim();
+      if (!candidate) continue;
+      assertDesignHtmlWellFormed({
+        content: annotateScreenHtmlForPersist(candidate, "html"),
+        filename: `variant-${slugify(variant.label.trim(), "option")}.html`,
+      });
+    }
+
     // Non-destructive bookkeeping: flag earlier still-complete variant sets
     // as superseded. Files are NEVER deleted automatically — a user's pick
     // exists only as a chat instruction until the agent's delete-file turn