@agent-native/core 0.101.7 → 0.101.11

package/corpus/templates/design/app/components/design/ReadOnlyDesignBanner.tsx

@@ -1,21 +1,66 @@
-import { IconInfoCircle } from "@tabler/icons-react";
+import { useT } from "@agent-native/core/client";
+import { IconInfoCircle, IconMessage } from "@tabler/icons-react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
 
 /**
  * Slim, non-blocking banner shown below the canvas when the current user only
  * has viewer access to the design (Figma-style "you can't edit this" notice).
- * Purely informational — editing affordances are already disabled elsewhere
- * via `canEditDesign`; this just tells the viewer why.
+ * Editing affordances are disabled elsewhere via `canEditDesign`; signed-in
+ * viewers get their one canvas action integrated into the same quiet notice.
  */
-export function ReadOnlyDesignBanner() {
+export function ReadOnlyDesignBanner({
+  pinMode = false,
+  onCommentPin,
+}: {
+  pinMode?: boolean;
+  onCommentPin?: () => void;
+}) {
+  const t = useT();
+  const commentLabel = pinMode
+    ? t("designEditor.stopPinningComments")
+    : t("designEditor.pinComment");
+
   return (
-    <div className="pointer-events-none absolute inset-x-0 bottom-0 z-30 flex items-center justify-center px-3 pb-2">
-      <div className="flex items-center gap-2 rounded-full border border-blue-500/30 bg-blue-500/10 px-3 py-1.5 text-xs text-blue-600 shadow-sm backdrop-blur-sm dark:text-blue-400">
+    <div
+      data-read-only-design-banner
+      className="pointer-events-none absolute inset-x-0 bottom-0 z-[50] flex items-center justify-center px-3 pb-2"
+    >
+      <div className="flex max-w-full items-center gap-2 rounded-full border border-blue-500/30 bg-blue-500/10 py-1 pe-1 ps-3 text-xs text-blue-600 shadow-sm backdrop-blur-sm dark:text-blue-400">
         <IconInfoCircle className="size-3.5 shrink-0" />
-        <span className="truncate">
+        <span className="min-w-0 truncate">
           {
             "You don't have access to edit this design" /* i18n-ignore Figma-style read-only notice */
           }
         </span>
+        {onCommentPin ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                className={cn(
+                  "pointer-events-auto size-7 shrink-0 rounded-full text-blue-600 hover:bg-blue-500/15 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300",
+                  pinMode &&
+                    "bg-blue-500/20 text-blue-700 dark:bg-blue-400/20 dark:text-blue-300",
+                )}
+                aria-label={commentLabel}
+                aria-pressed={pinMode}
+                onClick={onCommentPin}
+              >
+                <IconMessage className="size-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="top">{commentLabel}</TooltipContent>
+          </Tooltip>
+        ) : null}
       </div>
     </div>
   );

package/corpus/templates/design/app/components/design/ReviewCommentsPanel.tsx

@@ -15,6 +15,9 @@ import { cn } from "@/lib/utils";
 export interface ReviewCommentsPanelProps {
   designId: string;
   activeFileId?: string | null;
+  commentAnchor?: unknown | null;
+  commentMetadata?: Record<string, unknown>;
+  commentContextLabel?: string;
   canComment: boolean;
   /** Caller-derived editor capability for resolving threads. */
   canResolve?: boolean;
@@ -30,9 +33,27 @@ export interface ReviewCommentsPanelProps {
   className?: string;
 }
 
+type ReviewCommentsScope = "screen" | "all";
+
+export function resolveReviewComposerTargetId({
+  scope,
+  activeFileId,
+  commentAnchor,
+}: {
+  scope: ReviewCommentsScope;
+  activeFileId?: string | null;
+  commentAnchor?: unknown | null;
+}): string | null | undefined {
+  if (commentAnchor != null) return activeFileId;
+  return scope === "screen" ? activeFileId : undefined;
+}
+
 export function ReviewCommentsPanel({
   designId,
   activeFileId,
+  commentAnchor,
+  commentMetadata,
+  commentContextLabel,
   canComment,
   canResolve,
   canDeleteComment,
@@ -46,8 +67,13 @@ export function ReviewCommentsPanel({
   className,
 }: ReviewCommentsPanelProps) {
   const t = useT();
-  const [scope, setScope] = useState<"screen" | "all">("screen");
+  const [scope, setScope] = useState<ReviewCommentsScope>("screen");
   const targetId = scope === "screen" ? activeFileId : undefined;
+  const composerTargetId = resolveReviewComposerTargetId({
+    scope,
+    activeFileId,
+    commentAnchor,
+  });
 
   return (
     <div
@@ -87,6 +113,10 @@ export function ReviewCommentsPanel({
           resourceType="design"
           resourceId={designId}
           targetId={targetId}
+          composerTargetId={composerTargetId}
+          composerAnchor={commentAnchor}
+          composerMetadata={commentMetadata}
+          composerContextLabel={commentContextLabel}
           title={t("review.panelTitle")}
           placeholder={t("review.placeholder")}
           emptyState={t("review.emptyState")}
@@ -104,13 +134,15 @@ export function ReviewCommentsPanel({
           variant="plain"
           showComposer={canComment && showComposer}
           canReply={canComment}
-          canResolve={canResolve ?? canDispatchToAgent}
+          canResolve={canResolve ?? false}
           canDeleteComment={canDeleteComment}
-          showComposerTargetPicker={canComment && showComposer}
+          showComposerTargetPicker={
+            canComment && showComposer && canDispatchToAgent
+          }
           composerCommentLabel={t("review.commentMode")}
           composerAgentLabel={t("review.sendToAgent")}
           onCommentCreated={(comment) => {
-            if (comment.resolutionTarget === "agent") {
+            if (canDispatchToAgent && comment.resolutionTarget === "agent") {
               onDispatchCommentToAgent?.(comment);
             }
           }}

package/corpus/templates/design/app/components/visual-editor/ReviewCanvasPins.tsx

@@ -777,6 +777,7 @@ export function ReviewCanvasPins({
                 postDraft({ ...draftPin, resolutionTarget });
               }}
               resolutionTarget={draftPin.resolutionTarget}
+              showAgentAction={Boolean(onDispatchCommentToAgent)}
               placement={getReviewPopoverPlacement(draftPinPosition.point)}
               submitting={createComment.isPending}
             />
@@ -843,6 +844,7 @@ function DraftComposer({
   onCancel,
   onSubmit,
   resolutionTarget,
+  showAgentAction,
   placement,
   submitting,
 }: {
@@ -851,6 +853,7 @@ function DraftComposer({
   onCancel: () => void;
   onSubmit: (target: "agent" | "human") => void;
   resolutionTarget: "agent" | "human";
+  showAgentAction: boolean;
   placement: ReviewPopoverPlacement;
   submitting: boolean;
 }) {
@@ -886,7 +889,7 @@ function DraftComposer({
         onChange={onChange}
         onSubmit={onSubmit}
         submittingTarget={submitting ? resolutionTarget : null}
-        showAgentAction
+        showAgentAction={showAgentAction}
         placeholder={t("review.placeholder")}
         commentLabel={t("review.commentMode")}
         agentLabel={t("review.sendToAgent")}

package/corpus/templates/design/app/i18n/ar-SA.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "سجّل الدخول للتعليق",
     panelTitle: "الملاحظات",
     placeholder: "اترك ملاحظاتك…",
+    commentingOn: "التعليق على {{name}}",
     emptyState: "لا توجد تعليقات مراجعة بعد.",
     clickToPin: "انقر في أي مكان لتثبيت ملاحظة",
     escToExit: "اضغط Esc للخروج",

package/corpus/templates/design/app/i18n/de-DE.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "Zum Kommentieren anmelden",
     panelTitle: "Feedback",
     placeholder: "Feedback hinterlassen…",
+    commentingOn: "Kommentar zu {{name}}",
     emptyState: "Noch keine Prüfkommentare.",
     clickToPin: "Klicke an eine beliebige Stelle, um Feedback anzuheften",
     escToExit: "Esc zum Beenden",

package/corpus/templates/design/app/i18n/en-US.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "Sign in to comment",
     panelTitle: "Feedback",
     placeholder: "Leave feedback…",
+    commentingOn: "Commenting on {{name}}",
     emptyState: "No review comments yet.",
     clickToPin: "Click anywhere to pin feedback",
     escToExit: "Esc to exit",

package/corpus/templates/design/app/i18n/es-ES.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "Inicia sesión para comentar",
     panelTitle: "Opiniones",
     placeholder: "Deja tus comentarios…",
+    commentingOn: "Comentando en {{name}}",
     emptyState: "Aún no hay comentarios de revisión.",
     clickToPin: "Haz clic en cualquier lugar para fijar un comentario",
     escToExit: "Pulsa Esc para salir",

package/corpus/templates/design/app/i18n/fr-FR.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "Connectez-vous pour commenter",
     panelTitle: "Retours",
     placeholder: "Laissez un commentaire…",
+    commentingOn: "Commentaire sur {{name}}",
     emptyState: "Aucun commentaire de révision pour le moment.",
     clickToPin: "Cliquez n’importe où pour épingler un commentaire",
     escToExit: "Appuyez sur Esc pour quitter",

package/corpus/templates/design/app/i18n/hi-IN.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "टिप्पणी करने के लिए साइन इन करें",
     panelTitle: "प्रतिक्रिया",
     placeholder: "अपनी प्रतिक्रिया दें…",
+    commentingOn: "{{name}} पर टिप्पणी",
     emptyState: "अभी तक कोई समीक्षा टिप्पणी नहीं है।",
     clickToPin: "प्रतिक्रिया पिन करने के लिए कहीं भी क्लिक करें",
     escToExit: "बाहर निकलने के लिए Esc दबाएँ",

package/corpus/templates/design/app/i18n/ja-JP.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "コメントするにはサインイン",
     panelTitle: "フィードバック",
     placeholder: "フィードバックを入力…",
+    commentingOn: "{{name}} にコメント",
     emptyState: "レビューコメントはまだありません。",
     clickToPin: "任意の場所をクリックしてフィードバックを固定",
     escToExit: "Esc で終了",

package/corpus/templates/design/app/i18n/ko-KR.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "댓글을 작성하려면 로그인",
     panelTitle: "피드백",
     placeholder: "피드백을 남겨 주세요…",
+    commentingOn: "{{name}}에 댓글 작성",
     emptyState: "아직 검토 댓글이 없습니다.",
     clickToPin: "아무 곳이나 클릭하여 피드백 고정",
     escToExit: "Esc를 눌러 종료",

package/corpus/templates/design/app/i18n/pt-BR.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "Entre para comentar",
     panelTitle: "Feedback",
     placeholder: "Deixe seu feedback…",
+    commentingOn: "Comentando em {{name}}",
     emptyState: "Ainda não há comentários de revisão.",
     clickToPin: "Clique em qualquer lugar para fixar o feedback",
     escToExit: "Pressione Esc para sair",

package/corpus/templates/design/app/i18n/zh-CN.ts

@@ -12,6 +12,7 @@ const messages = {
     signInToComment: "登录后评论",
     panelTitle: "反馈",
     placeholder: "留下反馈…",
+    commentingOn: "正在评论 {{name}}",
     emptyState: "暂无审阅评论。",
     clickToPin: "点击任意位置固定反馈",
     escToExit: "按 Esc 退出",

package/corpus/templates/design/app/i18n/zh-TW.ts

@@ -53,6 +53,7 @@ const messages = {
     signInToComment: "登入後評論",
     panelTitle: "意見回饋",
     placeholder: "留下意見…",
+    commentingOn: "正在評論 {{name}}",
     emptyState: "目前沒有審閱評論。",
     clickToPin: "點選任意位置以固定意見",
     escToExit: "按 Esc 退出",

package/corpus/templates/design/app/pages/design-editor/selection-state.ts

@@ -483,6 +483,14 @@ export function shouldClearBridgeSelectionOnEmptyMarquee(args: {
   return args.resolvedCount === 0 && !args.additive;
 }
 
+/** Clear element context only when a selected review thread changes screens. */
+export function shouldClearSelectionForReviewThreadTarget(args: {
+  activeFileId?: string | null;
+  targetId?: string | null;
+}): boolean {
+  return Boolean(args.targetId && args.targetId !== args.activeFileId);
+}
+
 /**
  * PICK-RACE: MultiScreenCanvas's `onPick` prop is `(id: string) => void` — no
  * modifier/event info — even though a shift-click there already toggled a

package/corpus/templates/design/app/pages/design-editor/tool-state.ts

@@ -102,6 +102,17 @@ export function shouldAutoEnableDrawOverlay(args: {
   );
 }
 
+export type DesignBottomToolbarMode = "editor" | "commenter" | "hidden";
+
+export function getDesignBottomToolbarMode(args: {
+  isSignedIn: boolean;
+  canEditDesign: boolean;
+  hasActiveFile: boolean;
+}): DesignBottomToolbarMode {
+  if (!args.isSignedIn || !args.hasActiveFile) return "hidden";
+  return args.canEditDesign ? "editor" : "commenter";
+}
+
 export function getSingleScreenCreationTool(args: {
   activeTool: DesignTool;
   viewMode: "single" | "overview";

package/corpus/templates/design/changelog/2026-07-14-reviewers-can-now-pin-comments-from-the-canvas-toolbar-targe.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-14
+---
+
+Reviewers can now pin comments from the canvas toolbar, target selected layers, and only see actions they can use.

package/corpus/templates/design/changelog/2026-07-15-viewer-comment-controls-now-sit-inside-the-read-only-notice-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-15
+---
+
+Viewer comment controls now sit inside the read-only notice instead of floating over the canvas.

package/corpus/templates/design/shared/review-anchor.ts

@@ -14,6 +14,54 @@ export interface ResolvedReviewAnchor {
   source: "node" | "point";
 }
 
+export function createElementReviewAnchor(input: {
+  nodeId?: string | null;
+  rect?: { x: number; y: number; width: number; height: number } | null;
+  viewportWidth?: number | null;
+  viewportHeight?: number | null;
+}): DesignReviewAnchor | null {
+  const nodeId = input.nodeId?.trim() ?? "";
+  const rect = input.rect;
+  const hasRect = Boolean(
+    rect &&
+    Number.isFinite(rect.x) &&
+    Number.isFinite(rect.y) &&
+    Number.isFinite(rect.width) &&
+    rect.width > 0 &&
+    Number.isFinite(rect.height) &&
+    rect.height > 0 &&
+    typeof input.viewportWidth === "number" &&
+    Number.isFinite(input.viewportWidth) &&
+    input.viewportWidth > 0 &&
+    typeof input.viewportHeight === "number" &&
+    Number.isFinite(input.viewportHeight) &&
+    input.viewportHeight > 0,
+  );
+  if (!nodeId && !hasRect) return null;
+
+  const point = hasRect
+    ? {
+        xPct:
+          finitePercentage(
+            (((rect?.x ?? 0) + (rect?.width ?? 0) / 2) /
+              (input.viewportWidth as number)) *
+              100,
+          ) ?? 50,
+        yPct:
+          finitePercentage(
+            (((rect?.y ?? 0) + (rect?.height ?? 0) / 2) /
+              (input.viewportHeight as number)) *
+              100,
+          ) ?? 50,
+      }
+    : { xPct: 50, yPct: 50 };
+
+  return {
+    ...(nodeId ? { nodeId } : {}),
+    point,
+  };
+}
+
 function finitePercentage(value: unknown): number | null {
   if (typeof value !== "number" || !Number.isFinite(value)) return null;
   return Math.min(100, Math.max(0, value));

package/corpus/templates/mail/.agents/skills/email-drafts/SKILL.md

@@ -121,6 +121,23 @@ const drafts = await listAppState("compose-");
 
 The `send-email` action accepts an optional `attachments` array. Each entry must reference a file that was previously uploaded via the media-upload endpoint (`/api/media/upload`). Pass the server-side `filename` (the key returned by the upload endpoint, e.g. `abc123.pdf`), and optionally `originalName` (display name for the recipient) and `mimeType`. The attachment plumbing resolves the file from `data/uploads/` or from the configured file-storage URL recorded by the upload endpoint, then includes it as a MIME multipart attachment in the outgoing Gmail message. Do not store or paste attachment bytes, base64, or `data:` URLs in draft state/settings; files are never sent speculatively — only attach what the user has explicitly provided and confirmed.
 
+### Local files from an MCP host
+
+A hosted Mail app cannot read a path on the MCP host's local filesystem. Use
+`create-attachment-upload` with the file's display name. It returns a
+five-minute, owner-bound `uploadUrl`, a `PUT` method, and the attachment handle
+Mail expects. From the local host, upload the raw bytes directly:
+
+```bash
+curl --fail-with-body --request PUT --header '<Authorization header>' --data-binary @/absolute/path/to/report.pdf '<uploadUrl>'
+```
+
+Use the response's `attachment` object in the draft/send request. The upload
+Authorization header is a short-lived bearer credential: do not log, persist,
+reuse, or share it. Creating or consuming it does not send mail. Keep `send-email` behind its
+normal explicit-intent and human-approval gate; for drafting, pass the handle
+through `ask_app` or open the returned compose deep link.
+
 Example:
 ```json
 {

package/corpus/templates/mail/AGENTS.md

@@ -60,8 +60,9 @@ needed.
 - Never send mail unless the user explicitly asks to send. Draft or queue
   review by default. `send-email` has `needsApproval: true` — it is the
   canonical, intentionally rare use of the human-in-the-loop gate in this
-  framework; the loop pauses for approval on every real send. Drafting and
-  queueing are unaffected.
+  framework. An authenticated A2A caller may carry the user's exact chat
+  authorization for one matching send; otherwise the loop pauses for approval.
+  Drafting and queueing are unaffected.
 - When drafting, first read `get-mail-settings` for signature and writing
   style. Use `signature` exactly when present — draft-writing paths that build
   a `compose-*` entry (`manage-draft`, `open-queued-draft`) call
@@ -93,23 +94,24 @@ needed.
 
 ## Action Map
 
-| Action                                                                                                                                 | Purpose                                                                                |
-| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `search-emails` / `list-emails`                                                                                                        | Query across Gmail or local-fallback data by view/query.                               |
-| `get-email` / `get-thread`                                                                                                             | Full body/metadata for one message or thread.                                          |
-| `find-contact`                                                                                                                         | Resolve a name/partial address to a real email.                                        |
-| `get-hubspot-contact`                                                                                                                  | CRM contact + deals + tickets by email (HubSpot only).                                 |
-| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                         |
-| `send-email`                                                                                                                           | Real send. `needsApproval: true` — always pauses for human approval.                   |
-| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`                        | Teammate/Slack draft-review workflow — see `draft-queue`.                              |
-| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Per-message or per-thread state changes; most call `refresh-list` internally.          |
-| `manage-gmail-filters`                                                                                                                 | Provider-native Gmail filters (create/replace/delete).                                 |
-| `manage-automations` / `trigger-automations`                                                                                           | Natural-language inbox automation rules.                                               |
-| `respond-calendar-invite`                                                                                                              | Accept/decline/tentative an invite found in Mail.                                      |
-| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature`                                                                | Signature and writing-style settings.                                                  |
-| `manage-snippets`                                                                                                                      | List/create/update/delete saved reply snippets insertable from the compose slash menu. |
-| `get-tracking`                                                                                                                         | Open/click stats for a previously sent, tracked message.                               |
-| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                                                                  | Raw Gmail, Calendar, or HubSpot API calls beyond the canned actions.                   |
+| Action                                                                                                                                 | Purpose                                                                                                       |
+| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `search-emails` / `list-emails`                                                                                                        | Query across Gmail or local-fallback data by view/query.                                                      |
+| `get-email` / `get-thread`                                                                                                             | Full body/metadata for one message or thread.                                                                 |
+| `find-contact`                                                                                                                         | Resolve a name/partial address to a real email.                                                               |
+| `get-hubspot-contact`                                                                                                                  | CRM contact + deals + tickets by email (HubSpot only).                                                        |
+| `create-attachment-upload`                                                                                                             | Mint a five-minute, owner-bound raw-byte upload URL for one local attachment.                                 |
+| `manage-draft`                                                                                                                         | Create/update/delete a `compose-{id}` draft (signature-aware).                                                |
+| `send-email`                                                                                                                           | Real send. `needsApproval: true`; exact authenticated chat grants run once, otherwise it pauses for approval. |
+| `queue-email-draft` / `list-queued-drafts` / `update-queued-draft` / `open-queued-draft` / `send-queued-drafts`                        | Teammate/Slack draft-review workflow — see `draft-queue`.                                                     |
+| `mark-read` / `mark-thread-read` / `star-email` / `archive-email` / `unarchive-email` / `trash-email` / `untrash-email` / `move-email` | Per-message or per-thread state changes; most call `refresh-list` internally.                                 |
+| `manage-gmail-filters`                                                                                                                 | Provider-native Gmail filters (create/replace/delete).                                                        |
+| `manage-automations` / `trigger-automations`                                                                                           | Natural-language inbox automation rules.                                                                      |
+| `respond-calendar-invite`                                                                                                              | Accept/decline/tentative an invite found in Mail.                                                             |
+| `get-mail-settings` / `update-mail-settings` / `import-gmail-signature`                                                                | Signature and writing-style settings.                                                                         |
+| `manage-snippets`                                                                                                                      | List/create/update/delete saved reply snippets insertable from the compose slash menu.                        |
+| `get-tracking`                                                                                                                         | Open/click stats for a previously sent, tracked message.                                                      |
+| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                                                                  | Raw Gmail, Calendar, or HubSpot API calls beyond the canned actions.                                          |
 
 ## Application State
 

package/corpus/templates/mail/actions/create-attachment-upload.ts

@@ -0,0 +1,49 @@
+import { defineAction } from "@agent-native/core/action";
+import {
+  getAppProductionUrl,
+  getRequestUserEmail,
+  withConfiguredAppBasePath,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { createAttachmentUploadTicket } from "../server/lib/attachment-upload-ticket.js";
+
+const originalNameSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(255)
+  .refine(
+    (value) => !/[\\/\0\r\n]/.test(value),
+    "Filename must not contain path separators or control characters",
+  );
+
+export default defineAction({
+  description:
+    "Create a short-lived authenticated Mail upload URL for one local attachment. Upload the file bytes with HTTP PUT, then pass the returned attachment handle to ask_app so Mail can include it in a draft or approved send. Creating the URL does not send email.",
+  schema: z.object({
+    originalName: originalNameSchema.describe(
+      "Display filename, including its extension (for example, report.png)",
+    ),
+  }),
+  run: async ({ originalName }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("Authentication required");
+    const ticket = await createAttachmentUploadTicket(ownerEmail, originalName);
+    const appUrl = withConfiguredAppBasePath(getAppProductionUrl());
+    const uploadUrl = `${appUrl}/api/media/attachment-upload/${encodeURIComponent(ticket.uploadId)}`;
+    return {
+      method: "PUT" as const,
+      uploadUrl,
+      headers: { Authorization: `Bearer ${ticket.token}` },
+      expiresAt: new Date(ticket.expiresAt).toISOString(),
+      maxBytes: 10 * 1024 * 1024,
+      attachment: {
+        filename: ticket.filename,
+        originalName: ticket.originalName,
+        mimeType: ticket.mimeType,
+      },
+      next: "PUT the raw local file bytes to uploadUrl with the returned Authorization header before passing attachment to ask_app. Do not paste base64 into chat or action arguments.",
+    };
+  },
+});

package/corpus/templates/mail/changelog/2026-07-14-connected-agents-can-now-securely-upload-local-files-for-mai.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-14
+---
+
+Connected agents can now securely upload local attachments, honor an exact send you explicitly authorized in chat, and otherwise pause real sends for browser approval.