@agent-native/core 0.149.6 → 0.151.0

package/corpus/templates/tasks/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/dist/agent/run-store.js

@@ -1792,6 +1792,7 @@ export async function getRunStatus(runId) {
  * a second, competing truth.
  */
 const TURN_ENDING_ABORT_REASONS = new Set(["user", "displaced"]);
+const USER_INITIATED_ABORT_REASONS = new Set(["user", "abort"]);
 // Only infrastructure interruptions that the client can safely resume are
 // recoverable. An arbitrary caller-supplied abort reason must never become an
 // auto-continue signal, because that turns an explicit stop into new work.
@@ -1816,8 +1817,12 @@ export function terminalEventForAbortReason(reason) {
         };
     }
     if (TURN_ENDING_ABORT_REASONS.has(normalized) ||
+        USER_INITIATED_ABORT_REASONS.has(normalized) ||
         normalized.startsWith("user_")) {
-        return { type: "done" };
+        return {
+            type: "done",
+            ...(normalized !== "displaced" ? { reason: "user" } : {}),
+        };
     }
     return {
         type: "error",

package/dist/agent/thread-data-builder.js

@@ -3,13 +3,6 @@ import { isCredentialGapCodeAgentEvent, normalizeCodeAgentTranscript, } from "..
 const INTERRUPTED_TOOL_RESULT = "Interrupted before this tool returned a result.";
 export const ASSISTANT_RUN_DURATION_METADATA_KEY = "agentNativeRunDurationMs";
 const MAX_STORED_ATTACHMENT_CHARS = 60_000;
-/**
- * When no file-upload provider is configured we fall back to storing base64
- * directly in the SQL thread_data column. Cap the raw base64 per attachment to
- * avoid unbounded row growth. Attachments larger than this get a '[truncated]'
- * marker so the transcript still renders but the column stays sane.
- */
-const MAX_STORED_BASE64_BYTES = 2 * 1024 * 1024; // 2 MB per attachment
 function isInternalContinuationError(event) {
     const code = String(event.errorCode ?? "").toLowerCase();
     const msg = event.error.toLowerCase();
@@ -949,23 +942,6 @@ function textAttachmentEnvelope(att, text) {
     ].filter(Boolean);
     return `<attachment ${attrs.join(" ")}>\n${truncateStoredAttachment(text)}\n</attachment>`;
 }
-/**
- * Cap a base64 data-URL string for storage. When the encoded string is over
- * the limit we replace the base64 payload with a truncation marker so the
- * transcript still renders the attachment chip but doesn't bloat SQL.
- */
-function capBase64DataUrl(dataUrl) {
-    const commaIdx = dataUrl.indexOf(",");
-    if (commaIdx === -1)
-        return dataUrl;
-    const header = dataUrl.slice(0, commaIdx + 1);
-    const b64 = dataUrl.slice(commaIdx + 1);
-    // Each base64 char encodes 6 bits; 4 chars = 3 bytes.
-    const approxBytes = Math.floor((b64.length * 3) / 4);
-    if (approxBytes <= MAX_STORED_BASE64_BYTES)
-        return dataUrl;
-    return `${header}[base64 truncated — ${approxBytes.toLocaleString()} bytes exceeds storage limit]`;
-}
 function buildStoredAttachments(attachments, runId) {
     return (attachments ?? [])
         .map((att, index) => {
@@ -1008,17 +984,7 @@ function buildStoredAttachments(attachments, runId) {
                 },
             };
         }
-        if (att.type === "image" && att.data) {
-            return {
-                id,
-                type: "image",
-                name: att.name,
-                contentType: att.contentType,
-                status: { type: "complete" },
-                content: [{ type: "image", image: capBase64DataUrl(att.data) }],
-            };
-        }
-        if (att.data) {
+        if (typeof att.text === "string" && att.text.length > 0) {
             return {
                 id,
                 type: "file",
@@ -1026,25 +992,34 @@ function buildStoredAttachments(attachments, runId) {
                 contentType: att.contentType,
                 status: { type: "complete" },
                 content: [
-                    {
-                        type: "file",
-                        data: capBase64DataUrl(att.data),
-                        mimeType: att.contentType,
-                        filename: att.name,
-                    },
+                    { type: "text", text: textAttachmentEnvelope(att, att.text) },
                 ],
             };
         }
-        if (typeof att.text === "string" && att.text.length > 0) {
+        // Binary attachment data is request-scoped input, not thread state. If
+        // the provider was unavailable or failed, retain only a visible marker
+        // so the transcript can explain why the attachment needs storage setup
+        // without putting base64 bytes in SQL.
+        if (att.storageRequired === true || typeof att.data === "string") {
+            const uploadFailed = att.storageUploadFailed === true;
             return {
                 id,
-                type: "file",
+                type: att.type === "image" ? "image" : "file",
                 name: att.name,
                 contentType: att.contentType,
                 status: { type: "complete" },
                 content: [
-                    { type: "text", text: textAttachmentEnvelope(att, att.text) },
+                    {
+                        type: "text",
+                        text: uploadFailed
+                            ? "Attachment not retained: the configured object-storage upload failed. Retry the upload to keep files available throughout this thread."
+                            : "Attachment not retained: connect object storage to keep files available throughout this thread.",
+                    },
                 ],
+                metadata: {
+                    storageRequired: true,
+                    ...(uploadFailed ? { storageUploadFailed: true } : {}),
+                },
             };
         }
         return null;

package/dist/agent/types.d.ts

@@ -110,6 +110,17 @@ export interface AgentChatAttachment {
     type: string;
     name: string;
     data?: string;
+    /** Stable object-storage URL for this attachment, when uploaded. */
+    url?: string;
+    /** Provider that owns `url` (for example Builder or S3). */
+    uploadProvider?: string;
+    /** SVG and other unsafe files must stay references, never inline content. */
+    referenceOnly?: boolean;
+    securityNote?: string;
+    /** Set when the current turn could not create a durable object-storage URL. */
+    storageRequired?: boolean;
+    /** Set when a configured object-storage provider rejected or failed the upload. */
+    storageUploadFailed?: boolean;
     contentType?: string;
     text?: string;
 }
@@ -332,6 +343,8 @@ export type AgentChatEvent = {
     summary: string;
 } | {
     type: "done";
+    /** Set when a human explicitly stopped the current turn. */
+    reason?: "user";
 } | {
     type: "error";
     error: string;

package/dist/catalog.json

@@ -17,6 +17,7 @@
   "@tiptap/extension-horizontal-rule": "3.28.0",
   "@tiptap/extension-image": "3.28.0",
   "@tiptap/extension-link": "3.28.0",
+  "@tiptap/extension-list": "3.28.0",
   "@tiptap/extension-placeholder": "3.28.0",
   "@tiptap/extension-table": "3.28.0",
   "@tiptap/extension-table-cell": "3.28.0",

package/dist/cli/create.js

@@ -554,7 +554,7 @@ async function scaffoldWorkspaceRoot(targetDir, name) {
         const existing = fs.existsSync(wsPath)
             ? fs.readFileSync(wsPath, "utf-8")
             : "";
-        if (!existing.includes("catalog:")) {
+        if (!/^catalog:\s*$/m.test(existing)) {
             const catalogYaml = Object.entries(catalog)
                 .map(([k, v]) => `  "${k}": "${v}"`)
                 .join("\n");

package/dist/client/AssistantChat.js

@@ -19,7 +19,7 @@ import { AGENT_CHAT_VIEW_TRANSITION_PREPARE_EVENT } from "./chat-view-transition
 // ─── chat/ module imports ─────────────────────────────────────────────────────
 import { DownscalingImageAttachmentAdapter, BinaryDocumentAttachmentAdapter, MAX_ESTIMATED_BODY_BYTES, AGGRESSIVE_MAX_IMAGE_DIMENSION, AGGRESSIVE_JPEG_QUALITY, transcodeImageToDataURL, createAgentImageAttachments, serializeQueuedAttachments, estimateAttachmentBodyBytes, } from "./chat/attachment-adapters.js";
 import { TextStreamingContext } from "./chat/markdown-renderer.js";
-import { CheckpointContext, MessageActionsContext, assistantMessageRunId, UserMessage, AssistantMessage, SelectionAttachedPill, RunningActivityStatus, displayableUserMessageText, isHiddenUserMessage, ServerRunActiveContext, } from "./chat/message-components.js";
+import { CheckpointContext, MessageActionsContext, assistantMessageRunId, UserMessage, AssistantMessage, SelectionAttachedPill, RunningActivityStatus, displayableUserMessageText, isHiddenUserMessage, ServerRunActiveContext, UserStoppedRunContext, } from "./chat/message-components.js";
 import { repoHasAssistantMessage, getRepoMessages, getRepoMessage, shouldImportServerThreadData, dedupeRepoMessagesById, dropEmptyAssistantMessages, withLastAssistantRunDuration, } from "./chat/repo-helpers.js";
 import { BuilderSetupCard, BuilderSetupContent, LoopLimitContinueCard, RunErrorRecoveryCard, PlanModeCallout, getLoopLimitMetadata, getRunErrorMetadata, getRequestModeMetadata, runErrorKey, } from "./chat/run-recovery.js";
 import { createAgentChatRuntimeAdapter, } from "./chat/runtime.js";
@@ -3400,6 +3400,50 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
             });
         }
     }, [tabId, threadId, threadRuntime]);
+    const markVisibleRunStopped = useCallback(() => {
+        try {
+            const repo = normalizeThreadRepository(threadRuntime.export());
+            const messages = getRepoMessages(repo);
+            for (let index = messages.length - 1; index >= 0; index -= 1) {
+                const entry = messages[index];
+                const message = getRepoMessage(entry);
+                if (message?.role !== "assistant")
+                    continue;
+                const metadata = message.metadata ?? {};
+                const custom = metadata.custom && typeof metadata.custom === "object"
+                    ? metadata.custom
+                    : {};
+                if (custom.userStopped === true)
+                    return;
+                const nextMessage = {
+                    ...message,
+                    metadata: {
+                        ...metadata,
+                        custom: { ...custom, userStopped: true },
+                    },
+                };
+                const nextMessages = messages.slice();
+                nextMessages[index] =
+                    entry.message === undefined
+                        ? { ...entry, ...nextMessage }
+                        : { ...entry, message: nextMessage };
+                threadRuntime.import(ensureMessageMetadata({ ...repo, messages: nextMessages }));
+                return;
+            }
+        }
+        catch (err) {
+            captureError(err, {
+                tags: {
+                    source: "agent-chat-client",
+                    phase: "mark-user-stopped-run",
+                },
+                extra: {
+                    threadId: threadId ?? null,
+                    tabId: tabId ?? null,
+                },
+            });
+        }
+    }, [tabId, threadId, threadRuntime]);
     // Abort the active server run (identical to what the Stop button does) so
     // an immediate-while-running send can proceed cleanly without a 409 race.
     // Captured in a stable ref so addToQueue can call it without listing
@@ -3467,6 +3511,7 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
             reconnectTailOnlyRef.current = false;
         }
         settleVisibleInterruptedTools();
+        markVisibleRunStopped();
         threadRuntime.cancelRun();
         if (typeof window !== "undefined") {
             window.dispatchEvent(new CustomEvent("agentNative.chatRunning", {
@@ -3482,6 +3527,7 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
         applyLocalQueuedMessages,
         clearAutoResume,
         isReconnecting,
+        markVisibleRunStopped,
         resetRunningActivity,
         reconnectContent,
         settleVisibleInterruptedTools,
@@ -4142,14 +4188,14 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
                                                                                         return;
                                                                                     }
                                                                                     void addToQueue(suggestion);
-                                                                                }, className: "w-full px-2 py-1 text-center text-[13px] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2", children: suggestion }, suggestion))) })) : null, showInlineEmptyThreadFooterSlot ? (_jsx("div", { className: "agent-thread-footer-slot agent-thread-footer-slot--empty", children: resolvedThreadFooterSlot })) : null] })) : (_jsxs(MessageScrollerContent, { className: "agent-thread-content gap-4 px-4 py-4", children: [_jsx(AssistantMessageListErrorBoundary, { resetKey: messageListResetKey, children: _jsx(ThreadPrimitive.Messages
-                                                                            // assistant-ui indexes message parts through tap resources.
-                                                                            // Keep this key tied to that shape so clear/add transitions remount stale
-                                                                            // lookups without remounting on every streamed text update.
-                                                                            , { components: {
-                                                                                    UserMessage: AssistantChatUserMessageItem,
-                                                                                    AssistantMessage: AssistantChatAssistantMessageItem,
-                                                                                } }, messageListResetKey) }), visibleLoopLimit && !showRunningInUI && (_jsx(MessageScrollerItem, { children: _jsx(LoopLimitContinueCard, { info: visibleLoopLimit, onContinue: () => {
+                                                                                }, className: "w-full px-2 py-1 text-center text-[13px] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2", children: suggestion }, suggestion))) })) : null, showInlineEmptyThreadFooterSlot ? (_jsx("div", { className: "agent-thread-footer-slot agent-thread-footer-slot--empty", children: resolvedThreadFooterSlot })) : null] })) : (_jsxs(MessageScrollerContent, { className: "agent-thread-content gap-4 px-4 py-4", children: [_jsx(AssistantMessageListErrorBoundary, { resetKey: messageListResetKey, children: _jsx(UserStoppedRunContext.Provider, { value: wasRecentlyStoppedRun, children: _jsx(ThreadPrimitive.Messages
+                                                                                // assistant-ui indexes message parts through tap resources.
+                                                                                // Keep this key tied to that shape so clear/add transitions remount stale
+                                                                                // lookups without remounting on every streamed text update.
+                                                                                , { components: {
+                                                                                        UserMessage: AssistantChatUserMessageItem,
+                                                                                        AssistantMessage: AssistantChatAssistantMessageItem,
+                                                                                    } }, messageListResetKey) }) }), visibleLoopLimit && !showRunningInUI && (_jsx(MessageScrollerItem, { children: _jsx(LoopLimitContinueCard, { info: visibleLoopLimit, onContinue: () => {
                                                                                     setShowContinue(false);
                                                                                     setLoopLimitInfo(null);
                                                                                     addToQueue("Continue from where you left off.", undefined, undefined, undefined, undefined, "queued", "continue");
@@ -4216,7 +4262,9 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
                                                                                         isRunning,
                                                                                         requestedIntent: options?.intent,
                                                                                     }), undefined, true)
-                                                                                    : undefined, willQueue: engineSetupRequired || isRunning, onSlashCommand: onSlashCommand, execMode: execMode, onExecModeChange: onExecModeChange, planModeDisabled: planModeDisabled, planModeDisabledReason: planModeDisabledReason, selectedModel: selectedModel ?? defaultModel, selectedEffort: selectedEffort, availableModels: availableModels, modelListLoading: modelListLoading, onModelChange: onModelChange, onEffortChange: onEffortChange, imageModelMenu: imageModelMenu, onConnectProvider: onConnectProvider, onConnectLocalRuntime: onConnectLocalRuntime, toolbarSlot: composerToolbarSlot, contextItems: composerContextItems, onRemoveContextItem: removeComposerContextItem, plusMenuMode: plusMenuMode, layoutVariant: composerLayoutVariant, providerConnectStatusEnabled: providerStatusChecksEnabled, voiceEnabled: true, draftScope: threadId || tabId, interceptBuildRequestsForBuilder: true, onAttachmentError: setComposerError, extraActionButton: composerExtraActionButton, stopButton: showRunningInUI ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", onClick: () => stopActiveRun(), "aria-label": "Stop response", "data-agent-composer-slot": "stop-button", className: "shrink-0 flex h-7 w-7 cursor-pointer items-center justify-center rounded-full bg-primary text-primary-foreground shadow-sm transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2", children: _jsx(IconPlayerStopFilled, { className: "h-3 w-3" }) }) }), _jsx(TooltipContent, { children: "Stop response" })] })) : undefined })] })) }), showMissingKeySetup &&
+                                                                                    : undefined, willQueue: engineSetupRequired || isRunning, onSlashCommand: onSlashCommand, execMode: execMode, onExecModeChange: onExecModeChange, planModeDisabled: planModeDisabled, planModeDisabledReason: planModeDisabledReason, selectedModel: selectedModel ?? defaultModel, selectedEffort: selectedEffort, availableModels: availableModels, modelListLoading: modelListLoading, onModelChange: onModelChange, onEffortChange: onEffortChange, imageModelMenu: imageModelMenu, onConnectProvider: onConnectProvider, onConnectLocalRuntime: onConnectLocalRuntime, toolbarSlot: composerToolbarSlot, contextItems: composerContextItems, onRemoveContextItem: removeComposerContextItem, plusMenuMode: plusMenuMode, layoutVariant: composerLayoutVariant, providerConnectStatusEnabled: providerStatusChecksEnabled, voiceEnabled: true, draftScope: threadId || tabId, interceptBuildRequestsForBuilder: true, onAttachmentError: setComposerError, extraActionButton: composerExtraActionButton, stopButton: showRunningInUI ? (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", onClick: () => stopActiveRun({
+                                                                                                    preserveQueuedMessages: true,
+                                                                                                }), "aria-label": "Stop response", "data-agent-composer-slot": "stop-button", className: "shrink-0 flex h-7 w-7 cursor-pointer items-center justify-center rounded-full bg-primary text-primary-foreground shadow-sm transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2", children: _jsx(IconPlayerStopFilled, { className: "h-3 w-3" }) }) }), _jsx(TooltipContent, { children: "Stop response" })] })) : undefined })] })) }), showMissingKeySetup &&
                                                                     !showInlineMissingKeySetup ? (_jsx(PopoverContent, { side: missingApiKeySetupLayout === "sidebar"
                                                                         ? "top"
                                                                         : "bottom", align: "center", sideOffset: 8, collisionPadding: 12, "data-agent-native-composer-popover": "true", className: "z-[260] box-border w-[min(calc(100vw-2rem),var(--radix-popover-content-available-width,26rem),26rem)] rounded-lg border-border p-3 shadow-lg", children: _jsx(BuilderSetupContent, { onConnected: handleBuilderConnected, layout: missingApiKeySetupLayout }) })) : null] })] })] }) }) }) }) }) }) }) }) }) }));

package/dist/client/FileStorageSetupCard.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Inline storage setup shown when an attachment cannot be made durable.
+ * Builder connect and the custom-key path intentionally share the same
+ * surface so the user does not have to understand provider internals first.
+ */
+export declare function FileStorageSetupCard(): import("react").JSX.Element;

package/dist/client/FileStorageSetupCard.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ActionButton } from "@agent-native/toolkit/design-system";
+import { BuilderConnectCard, DefaultBuilderConnectCardView, } from "./setup-connections/BuilderConnectCard.js";
+/**
+ * Inline storage setup shown when an attachment cannot be made durable.
+ * Builder connect and the custom-key path intentionally share the same
+ * surface so the user does not have to understand provider internals first.
+ */
+export function FileStorageSetupCard() {
+    const openCustomStorage = () => {
+        if (typeof window === "undefined")
+            return;
+        window.dispatchEvent(new CustomEvent("agent-panel:open-settings", {
+            detail: { section: "uploads" },
+        }));
+    };
+    return (_jsx("div", { className: "space-y-2", "data-testid": "file-storage-setup-card", children: _jsx(BuilderConnectCard, { title: "Connect Builder for file storage", description: "Builder keeps uploaded images and files on durable object storage so the agent can reuse them throughout this thread.", trackingSource: "file_upload_chat_card", render: ({ viewModel, className }) => (_jsxs("div", { className: "space-y-2", children: [_jsx(DefaultBuilderConnectCardView, { viewModel: viewModel, className: className }), _jsxs(ActionButton, { type: "button", intent: "neutral", emphasis: "outline", size: "compact", onPress: openCustomStorage, className: "h-auto w-full justify-start rounded-md px-3 py-2 text-left text-xs font-medium text-foreground", children: ["Use custom storage keys", _jsx("span", { className: "mt-0.5 block text-[11px] font-normal text-muted-foreground", children: "Configure an S3-compatible bucket with a stable public URL." })] })] })) }) }));
+}

package/dist/client/NewWorkspaceAppFlow.js

@@ -241,6 +241,16 @@ export function NewWorkspaceAppFlow({ sourceApp = "chat", className = "", dispat
                     setBranchUrl(result?.url || null);
                     setStatusMessage("Builder branch created.");
                 }
+                else if (result?.mode === "local-agent") {
+                    sendToAgentChat({
+                        message: result.prompt ?? message,
+                        submit: true,
+                        type: "code",
+                        newTab: true,
+                        reuseEmptyTab: true,
+                    });
+                    setStatusMessage("Sent to the local agent.");
+                }
                 else {
                     setStatusMessage(result?.message ||
                         "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.");

package/dist/client/agent-chat-adapter.js

@@ -217,6 +217,11 @@ const BACKGROUND_CONTINUATION_TERMINAL_REASONS = new Set([
     "network_interrupted",
     "no_progress",
 ]);
+function isUserInitiatedTerminalReason(reason) {
+    return (reason === "aborted:user" ||
+        reason === "aborted:abort" ||
+        reason.startsWith("aborted:user_"));
+}
 /**
  * True when the given `/runs/active` snapshot, if surfaced as a background
  * terminal outcome right now, would render as an error rather than a
@@ -230,6 +235,8 @@ function isBackgroundTerminalErrorOutcome(lastKnown) {
     const rawTerminalReason = typeof lastKnown?.terminalReason === "string"
         ? lastKnown.terminalReason
         : "";
+    if (isUserInitiatedTerminalReason(rawTerminalReason))
+        return false;
     const hasErrorTerminalReason = rawTerminalReason.startsWith("error:");
     const terminalReason = rawTerminalReason.replace(/^error:/, "");
     const mappedMessage = terminalReason
@@ -360,37 +367,73 @@ function extractAttachmentsFromMessage(message) {
     for (const att of message.attachments ?? []) {
         for (const part of att.content) {
             if (part.type === "image" && typeof part.image === "string") {
+                const persistedMetadata = att && typeof att.metadata === "object"
+                    ? att.metadata
+                    : undefined;
+                const imageIsDataUrl = part.image.startsWith("data:");
                 attachments.push({
                     type: "image",
                     name: att.name,
                     contentType: att.contentType,
-                    data: part.image,
+                    ...(imageIsDataUrl ? { data: part.image } : { url: part.image }),
+                    ...(typeof persistedMetadata?.uploadProvider === "string"
+                        ? { uploadProvider: persistedMetadata.uploadProvider }
+                        : {}),
+                    ...(persistedMetadata?.referenceOnly === true
+                        ? {
+                            referenceOnly: true,
+                            ...(typeof persistedMetadata.securityNote === "string"
+                                ? { securityNote: persistedMetadata.securityNote }
+                                : {}),
+                        }
+                        : {}),
                 });
             }
-            else if (part.type === "file" && typeof part.data === "string") {
+            else if (part.type === "file" &&
+                (typeof part.data === "string" || typeof part.url === "string")) {
                 const contentType = att.contentType ??
                     (typeof part.mimeType === "string" ? part.mimeType : undefined);
-                const preserveDataUrl = part.data.startsWith("data:") &&
+                const data = typeof part.data === "string" ? part.data : undefined;
+                const url = typeof part.url === "string" ? part.url : undefined;
+                const persistedMetadata = att && typeof att.metadata === "object"
+                    ? att.metadata
+                    : undefined;
+                const preserveDataUrl = typeof data === "string" &&
+                    data.startsWith("data:") &&
                     shouldPreserveFileDataUrl({ name: att.name, contentType });
-                const decodedText = part.data.startsWith("data:")
-                    ? decodeTextDataUrl(part.data)
+                const decodedText = data?.startsWith("data:")
+                    ? decodeTextDataUrl(data)
                     : null;
                 attachments.push({
                     type: "file",
                     name: att.name,
                     contentType,
+                    ...(url ? { url } : {}),
                     ...(preserveDataUrl
                         ? {
-                            data: part.data,
+                            data,
                             ...(decodedText !== null
                                 ? { text: truncateOutboundAttachment(decodedText) }
                                 : {}),
                         }
                         : decodedText !== null
                             ? { text: truncateOutboundAttachment(decodedText) }
-                            : part.data.startsWith("data:")
-                                ? { data: part.data }
-                                : { text: truncateOutboundAttachment(part.data) }),
+                            : data?.startsWith("data:")
+                                ? { data }
+                                : url
+                                    ? {}
+                                    : { text: truncateOutboundAttachment(data ?? "") }),
+                    ...(typeof persistedMetadata?.uploadProvider === "string"
+                        ? { uploadProvider: persistedMetadata.uploadProvider }
+                        : {}),
+                    ...(persistedMetadata?.referenceOnly === true
+                        ? {
+                            referenceOnly: true,
+                            ...(typeof persistedMetadata.securityNote === "string"
+                                ? { securityNote: persistedMetadata.securityNote }
+                                : {}),
+                        }
+                        : {}),
                 });
             }
             else if (part.type === "text" && typeof part.text === "string") {
@@ -405,11 +448,12 @@ function extractAttachmentsFromMessage(message) {
     }
     for (const part of message.content ?? []) {
         if (part.type === "image" && typeof part.image === "string") {
+            const imageIsDataUrl = part.image.startsWith("data:");
             attachments.push({
                 type: "image",
                 name: "image",
                 contentType: /^data:([^;,]+)/.exec(part.image)?.[1],
-                data: part.image,
+                ...(imageIsDataUrl ? { data: part.image } : { url: part.image }),
             });
         }
     }
@@ -447,11 +491,15 @@ function attachmentHistoryText(attachment) {
             attachment.type
                 ? `type="${escapeAttachmentAttribute(attachment.type)}"`
                 : null,
+            attachment.url
+                ? `url="${escapeAttachmentAttribute(attachment.url)}"`
+                : null,
         ].filter(Boolean);
         return `<attachment ${attrs.join(" ")}>\n${truncateHistoryAttachment(attachment.text)}\n</attachment>`;
     }
     if (attachment.name) {
-        return `[Attached ${attachment.type || "file"}: ${attachment.name}${attachment.contentType ? ` (${attachment.contentType})` : ""}]`;
+        const hostedUrl = attachment.url ? `; hosted URL: ${attachment.url}` : "";
+        return `[Attached ${attachment.type || "file"}: ${attachment.name}${attachment.contentType ? ` (${attachment.contentType})` : ""}${hostedUrl}]`;
     }
     return null;
 }
@@ -2071,6 +2119,27 @@ export function createAgentChatAdapter(options) {
                     const rawTerminalReason = typeof lastKnown?.terminalReason === "string"
                         ? lastKnown.terminalReason
                         : "";
+                    if (isUserInitiatedTerminalReason(rawTerminalReason)) {
+                        settleInterruptedToolCalls(content, undefined, {
+                            includeActivity: true,
+                        });
+                        settleTerminalChatRun();
+                        yield {
+                            content: [...content],
+                            status: {
+                                type: "complete",
+                                reason: "stop",
+                            },
+                            metadata: {
+                                custom: {
+                                    ...(runId ? { runId } : {}),
+                                    userStopped: true,
+                                },
+                            },
+                        };
+                        clearActiveRun();
+                        return;
+                    }
                     // terminal_reason is either a bare reason ("dispatch_payload_missing")
                     // or "error:<errorCode>" when derived from a terminal error event.
                     const hasErrorTerminalReason = rawTerminalReason.startsWith("error:");
@@ -2406,6 +2475,13 @@ export function createAgentChatAdapter(options) {
                         if (activeRunId && isOurRun) {
                             lastSeenActive = active;
                             updateCurrentRunDispatchMode(active?.dispatchMode);
+                            const activeTerminalReason = typeof active?.terminalReason === "string"
+                                ? active.terminalReason
+                                : "";
+                            if (isUserInitiatedTerminalReason(activeTerminalReason)) {
+                                yield* emitBackgroundTerminalOutcome(active);
+                                return "completed";
+                            }
                             const isTerminal = activeStatus === "completed" || activeStatus === "errored";
                             if (isTerminal && replayedTerminalRunIds.has(activeRunId)) {
                                 if (lastAutoContinueReason === "stale_run" &&

package/dist/client/agent-chat.d.ts

@@ -23,7 +23,7 @@ export interface AgentChatMessage {
     referenceImagePaths?: string[];
     /** Optional uploaded reference images */
     uploadedReferenceImages?: string[];
-    /** Optional image data URLs to include in the submitted chat message */
+    /** Optional image data URLs or durable image URLs to include in the submitted chat message */
     images?: string[];
     /** Stable tab identifier — auto-generated if omitted */
     tabId?: string;

package/dist/client/agent-chat.js

@@ -561,9 +561,14 @@ export function parseSubmitChatMessage(event) {
     const message = typeof raw.message === "string" ? raw.message : "";
     if (!message)
         return null;
-    const images = Array.isArray(raw.images)
-        ? raw.images.filter((image) => typeof image === "string" && image.length > 0)
-        : undefined;
+    const imageSources = [
+        ...(Array.isArray(raw.images) ? raw.images : []),
+        ...(Array.isArray(raw.referenceImagePaths) ? raw.referenceImagePaths : []),
+        ...(Array.isArray(raw.uploadedReferenceImages)
+            ? raw.uploadedReferenceImages
+            : []),
+    ].filter((image) => typeof image === "string" && image.trim().length > 0);
+    const images = imageSources.length > 0 ? [...new Set(imageSources)] : undefined;
     return {
         message,
         context: typeof raw.context === "string" ? raw.context : undefined,

package/dist/client/chat/attachment-adapters.js

@@ -267,6 +267,16 @@ export function serializeAttachmentContentPart(part) {
             ...(typeof part.filename === "string" ? { filename: part.filename } : {}),
         };
     }
+    if (part.type === "file" && typeof part.url === "string") {
+        return {
+            type: "file",
+            url: part.url,
+            mimeType: typeof part.mimeType === "string"
+                ? part.mimeType
+                : "application/octet-stream",
+            ...(typeof part.filename === "string" ? { filename: part.filename } : {}),
+        };
+    }
     return null;
 }
 export async function serializeQueuedAttachments(attachments) {

package/dist/client/chat/message-components.d.ts

@@ -51,6 +51,7 @@ export declare function shouldOfferRestore(args: {
 export declare function assistantMessageRunId(message: unknown): string | undefined;
 /** Stable logical-turn identity shared by chained continuation run IDs. */
 export declare function assistantMessageTurnId(message: unknown): string | undefined;
+export declare function assistantMessageWasUserStopped(message: unknown): boolean;
 export declare function resolveAssistantRequestId(message: unknown, activeRun: {
     threadId: string;
     runId: string;
@@ -91,13 +92,15 @@ export declare function shouldShowAssistantMessageFooter({ isLast, chatRunning,
  * that the agent stopped.
  */
 export declare const ServerRunActiveContext: React.Context<boolean>;
-export declare function shouldShowMissingFinalResponse({ isCurrentTurnRunning, serverRunActive, statusIsTerminal, hasAssistantText, hasUnresolvedTool, hasCompletedCustomUi, }: {
+export declare const UserStoppedRunContext: React.Context<(runId?: string) => boolean>;
+export declare function shouldShowMissingFinalResponse({ isCurrentTurnRunning, serverRunActive, statusIsTerminal, hasAssistantText, hasUnresolvedTool, hasCompletedCustomUi, userStoppedRun, }: {
     isCurrentTurnRunning: boolean;
     serverRunActive?: boolean;
     statusIsTerminal: boolean;
     hasAssistantText: boolean;
     hasUnresolvedTool: boolean;
     hasCompletedCustomUi?: boolean;
+    userStoppedRun?: boolean;
 }): boolean;
 export declare function useSettledFlag(active: boolean, delayMs: number): boolean;
 export declare function shouldShowAssistantWorkSummary({ isLast, isComplete, hasCollapsibleWork, hasUnresolvedTool, chatRunning, }: {