@agent-native/core 0.149.5 → 0.151.0

package/dist/file-upload/pre-upload-attachments.d.ts

@@ -30,10 +30,14 @@ export interface PreUploadAttachmentsResult {
     /** Uploaded non-image files (PDF, generic binary). Parallel to `uploaded`
      *  but for the file/document attachment type. */
     uploadedFiles: PreUploadedFileAttachment[];
-    /** True if at least one image attachment failed to upload because no
-     *  file-upload provider is configured. Templates use this to render a
-     *  "Connect Builder.io" suggestion. */
+    /** True if at least one image or file could not be uploaded because no
+     *  file-upload provider is configured. The agent uses this to render the
+     *  storage setup card. */
     providerMissing: boolean;
+    /** True if at least one configured provider failed while uploading. */
+    uploadFailed: boolean;
+    /** The first provider error, bounded for safe inclusion in the chat hint. */
+    uploadError?: string;
     /** A pre-formatted block to inject into the user message text so the agent
      *  has each hosted URL inline. Null when nothing was uploaded or no provider
      *  is configured. */
@@ -41,18 +45,18 @@ export interface PreUploadAttachmentsResult {
 }
 /**
  * Returns true when a file-upload provider is currently configured.
- * Used to decide whether to attempt upload-first or fall back to base64.
+ * Used to decide whether an attachment can be uploaded before the agent turn.
  */
 export declare function isFileUploadProviderConfigured(): boolean;
 /**
  * Pre-upload chat image attachments through the active file-upload provider
  * (Builder.io by default) so the agent can embed hosted URLs in HTML, slide
- * content, and outbound messages. Keeps the original base64 data URL on the
- * attachment so multimodal vision still works — only adds a hosted `url`.
+ * content, and outbound messages. Keeps the original data URL in memory for
+ * the current multimodal turn and adds a hosted `url`.
  *
  * Safe to call when no provider is configured: it returns the attachments
- * untouched with `providerMissing: true` so callers can surface a connect-
- * Builder.io hint to the agent.
+ * untouched with `providerMissing: true` so callers can surface the storage
+ * setup card to the agent without persisting the binary payload.
  */
 export declare function preUploadImageAttachments(opts: {
     attachments: AgentChatAttachment[] | undefined;
@@ -66,8 +70,9 @@ export declare function preUploadImageAttachments(opts: {
  * file-reading still work; callers that persist the attachment can drop the
  * data when a URL exists.
  *
- * Falls back gracefully when no provider is configured: returns untouched
- * attachments with `providerMissing: true` for image-type failures.
+ * When no provider is configured, returns untouched in-memory attachments with
+ * `providerMissing: true`. The caller may still use the bytes for this turn,
+ * but must not persist them as SQL/base64 attachment data.
  */
 export declare function preUploadAttachments(opts: {
     attachments: AgentChatAttachment[] | undefined;

package/dist/file-upload/pre-upload-attachments.js

@@ -33,7 +33,7 @@ function escapeXmlAttr(value) {
 }
 /**
  * Returns true when a file-upload provider is currently configured.
- * Used to decide whether to attempt upload-first or fall back to base64.
+ * Used to decide whether an attachment can be uploaded before the agent turn.
  */
 export function isFileUploadProviderConfigured() {
     return getActiveFileUploadProvider() !== null;
@@ -41,12 +41,12 @@ export function isFileUploadProviderConfigured() {
 /**
  * Pre-upload chat image attachments through the active file-upload provider
  * (Builder.io by default) so the agent can embed hosted URLs in HTML, slide
- * content, and outbound messages. Keeps the original base64 data URL on the
- * attachment so multimodal vision still works — only adds a hosted `url`.
+ * content, and outbound messages. Keeps the original data URL in memory for
+ * the current multimodal turn and adds a hosted `url`.
  *
  * Safe to call when no provider is configured: it returns the attachments
- * untouched with `providerMissing: true` so callers can surface a connect-
- * Builder.io hint to the agent.
+ * untouched with `providerMissing: true` so callers can surface the storage
+ * setup card to the agent without persisting the binary payload.
  */
 export async function preUploadImageAttachments(opts) {
     return preUploadAttachments({ ...opts, includeFiles: false });
@@ -59,8 +59,9 @@ export async function preUploadImageAttachments(opts) {
  * file-reading still work; callers that persist the attachment can drop the
  * data when a URL exists.
  *
- * Falls back gracefully when no provider is configured: returns untouched
- * attachments with `providerMissing: true` for image-type failures.
+ * When no provider is configured, returns untouched in-memory attachments with
+ * `providerMissing: true`. The caller may still use the bytes for this turn,
+ * but must not persist them as SQL/base64 attachment data.
  */
 export async function preUploadAttachments(opts) {
     const list = Array.isArray(opts.attachments) ? opts.attachments : [];
@@ -68,12 +69,15 @@ export async function preUploadAttachments(opts) {
     const uploaded = [];
     const uploadedFiles = [];
     let providerMissing = false;
+    let uploadFailed = false;
+    let uploadError;
     if (list.length === 0) {
         return {
             attachments: list,
             uploaded,
             uploadedFiles,
             providerMissing: false,
+            uploadFailed: false,
             injectedText: null,
         };
     }
@@ -82,11 +86,9 @@ export async function preUploadAttachments(opts) {
         const isFile = att.type === "file" || att.type === "document";
         if (!isImage && !(includeFiles && isFile))
             continue;
-        if (typeof att.data !== "string")
-            continue;
-        if (att.url) {
+        if (typeof att.url === "string" && att.url.trim()) {
             // Already pre-uploaded earlier in the pipeline — reuse it.
-            const isReferenceOnlySvg = isSvgAttachment(att);
+            const isReferenceOnlySvg = att.referenceOnly === true || isSvgAttachment(att);
             if (isReferenceOnlySvg) {
                 markReferenceOnlySvgAttachment(att, att.contentType);
             }
@@ -110,7 +112,21 @@ export async function preUploadAttachments(opts) {
             }
             continue;
         }
-        const match = att.data.match(FILE_DATA_URL_RE);
+        let data = att.data;
+        if (typeof data !== "string" &&
+            includeFiles &&
+            isFile &&
+            typeof att.text === "string" &&
+            att.text.length > 0) {
+            // Text attachments are already decoded by the client. Upload the text
+            // bytes too so a later turn has the same durable object URL as binary
+            // attachments instead of a SQL-only scratch copy.
+            const encoded = Buffer.from(att.text, "utf8").toString("base64");
+            data = `data:${normalizeContentType(att.contentType) || "text/plain"};base64,${encoded}`;
+        }
+        if (typeof data !== "string")
+            continue;
+        const match = data.match(FILE_DATA_URL_RE);
         if (!match)
             continue;
         const dataUrlMimeType = normalizeContentType(match[1]);
@@ -134,8 +150,8 @@ export async function preUploadAttachments(opts) {
                 ownerEmail: opts.ownerEmail || undefined,
             });
             if (!result) {
-                if (uploadAsImage)
-                    providerMissing = true;
+                providerMissing = true;
+                att.storageRequired = true;
                 continue;
             }
             att.url = result.url;
@@ -168,8 +184,12 @@ export async function preUploadAttachments(opts) {
             }
         }
         catch (err) {
-            // Real upload failure (network, API). Keep the base64 so the model
-            // can still see the image/file, but don't crash the turn.
+            // Real upload failure (network, API). Keep the bytes in memory for the
+            // current turn, but never treat the failure as a durable upload.
+            att.storageRequired = true;
+            att.storageUploadFailed = true;
+            uploadFailed = true;
+            uploadError ??= (err instanceof Error ? err.message : String(err)).slice(0, 500);
             console.warn("[agent-native] pre-upload of chat attachment failed:", err instanceof Error ? err.message : String(err));
         }
     }
@@ -199,21 +219,43 @@ export async function preUploadAttachments(opts) {
             lines.push(`<chat-file-attachment ${attrs.join(" ")} />`);
         }
         const hasReferenceOnlySvg = uploadedFiles.some((file) => file.referenceOnly && isSvgAttachment(file));
-        injectedText = [
+        const linesWithMetadata = [
             hasReferenceOnlySvg
                 ? '<chat-attachments note="The user attached these files. Image attachment URLs may be used for embedding. File attachment URLs are references; SVG files are unsanitized vector source and must not be inlined as HTML or embedded in outbound content unless the target app sanitizes or stores them safely.">'
                 : '<chat-attachments note="The user attached these files. Image attachment URLs may be used for embedding in HTML, slide content, or outbound messages. File attachment URLs are references for reading or attaching in target apps.">',
             ...lines,
             "</chat-attachments>",
-        ].join("\n");
+        ];
+        if (providerMissing || uploadFailed) {
+            const failureLines = [
+                providerMissing
+                    ? "One or more attachments could not be stored because no durable object-storage provider is configured."
+                    : null,
+                uploadFailed
+                    ? `A configured object-storage provider failed to upload an attachment${uploadError ? `: ${escapeXmlAttr(uploadError)}` : "."}`
+                    : null,
+            ].filter((line) => Boolean(line));
+            linesWithMetadata.push("<chat-file-attachment-upload-error>", ...failureLines, ...(providerMissing
+                ? [
+                    "Call `connect-file-storage` now so the user can connect Builder or configure custom storage keys, then continue using the hosted references.",
+                ]
+                : [
+                    "Retry the upload or inspect the configured storage provider. Do not claim the attachment is durably available until it succeeds.",
+                ]), "</chat-file-attachment-upload-error>");
+        }
+        injectedText = linesWithMetadata.join("\n");
     }
-    else if (providerMissing) {
+    else if (providerMissing || uploadFailed) {
         injectedText = [
-            "<chat-image-attachment-upload-error>",
-            "The user attached one or more images, but no file-upload provider is configured for this app.",
-            "If `connect-builder` is available, use it to render the inline Builder.io connection card. Workspaces with a custom storage provider can also use one registered via registerFileUploadProvider().",
-            "Until that's done, you can still SEE the image, but you do NOT have a URL to embed it in HTML or share with other apps.",
-            "</chat-image-attachment-upload-error>",
+            "<chat-file-attachment-upload-error>",
+            providerMissing
+                ? "The user attached one or more images or files, but durable object storage is not configured for this app."
+                : `The user attached one or more images or files, but the configured storage provider failed to upload them${uploadError ? `: ${escapeXmlAttr(uploadError)}` : "."}`,
+            providerMissing
+                ? "Call `connect-file-storage` now to render the inline storage setup card. The user can connect Builder for managed storage or open the same card's custom-key setup for S3-compatible object storage."
+                : "Retry the upload or inspect the configured storage provider. Do not claim the attachment is durably available until it succeeds.",
+            "Do not persist the base64 contents in SQL. Until storage succeeds, use the attachment only for this turn.",
+            "</chat-file-attachment-upload-error>",
         ].join("\n");
     }
     return {
@@ -221,6 +263,8 @@ export async function preUploadAttachments(opts) {
         uploaded,
         uploadedFiles,
         providerMissing,
+        uploadFailed,
+        ...(uploadError ? { uploadError } : {}),
         injectedText,
     };
 }

package/dist/file-upload/registry.d.ts

@@ -9,15 +9,14 @@ export declare function listFileUploadProviders(): FileUploadProvider[];
 /**
  * Returns the first configured provider, checking user-registered ones first
  * and falling back to the built-in Builder.io provider when its env is set.
- * Returns `null` when nothing is configured — callers should then use the
- * SQL fallback.
+ * Returns `null` when nothing is configured. Callers must fail closed rather
+ * than persisting the original binary payload in SQL.
  */
 export declare function getActiveFileUploadProvider(): FileUploadProvider | null;
 export declare function getActiveFileUploadProviderForRequest(): Promise<FileUploadProvider | null>;
 /**
  * Upload a file via the active provider, or `null` if no provider is
- * configured. Callers use `null` as the signal to fall back to SQL
- * storage. On the first fallback we log a one-time warning because
- * storing files in SQL is not optimal for production.
+ * configured. `null` is an explicit storage-setup state: callers must not
+ * turn the input into a base64 SQL fallback.
  */
 export declare function uploadFile(input: FileUploadInput): Promise<FileUploadResult | null>;

package/dist/file-upload/registry.js

@@ -18,8 +18,8 @@ export function listFileUploadProviders() {
 /**
  * Returns the first configured provider, checking user-registered ones first
  * and falling back to the built-in Builder.io provider when its env is set.
- * Returns `null` when nothing is configured — callers should then use the
- * SQL fallback.
+ * Returns `null` when nothing is configured. Callers must fail closed rather
+ * than persisting the original binary payload in SQL.
  */
 export function getActiveFileUploadProvider() {
     for (const provider of providers.values()) {
@@ -36,14 +36,8 @@ export async function getActiveFileUploadProviderForRequest() {
         if (provider.isConfigured())
             return provider;
         if (provider.isConfiguredForRequest) {
-            try {
-                if (await provider.isConfiguredForRequest())
-                    return provider;
-            }
-            catch {
-                // Treat failed scoped credential lookups as unavailable. The upload
-                // call will surface real provider errors after a provider is selected.
-            }
+            if (await provider.isConfiguredForRequest())
+                return provider;
         }
     }
     if (builderFileUploadProvider.isConfigured()) {
@@ -62,9 +56,8 @@ export async function getActiveFileUploadProviderForRequest() {
 }
 /**
  * Upload a file via the active provider, or `null` if no provider is
- * configured. Callers use `null` as the signal to fall back to SQL
- * storage. On the first fallback we log a one-time warning because
- * storing files in SQL is not optimal for production.
+ * configured. `null` is an explicit storage-setup state: callers must not
+ * turn the input into a base64 SQL fallback.
  */
 export async function uploadFile(input) {
     const provider = await getActiveFileUploadProviderForRequest();
@@ -85,7 +78,7 @@ export async function uploadFile(input) {
     }
     catch (err) {
         // DB unavailable or credential store not ready — can't resolve key.
-        // Log and fall through to the SQL fallback below.
+        // Return an unavailable-provider state below; never fall back to SQL.
         console.warn("[agent-native] Builder credential check failed:", err instanceof Error ? err.message : String(err));
     }
     if (builderKey) {

package/dist/file-upload/s3.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Framework-owned S3-compatible object storage provider.
+ *
+ * The onboarding form writes these keys to scoped secrets. A public base URL
+ * is required because chat attachments need stable URLs that remain usable
+ * after the request and across later turns in the thread.
+ */
+import type { FileUploadProvider } from "./types.js";
+export declare const s3FileUploadProvider: FileUploadProvider;

package/dist/file-upload/s3.js

@@ -0,0 +1,168 @@
+/**
+ * Framework-owned S3-compatible object storage provider.
+ *
+ * The onboarding form writes these keys to scoped secrets. A public base URL
+ * is required because chat attachments need stable URLs that remain usable
+ * after the request and across later turns in the thread.
+ */
+import { resolveSecret } from "../server/credential-provider.js";
+function cleanValue(value) {
+    const cleaned = value?.trim();
+    return cleaned ? cleaned : undefined;
+}
+function buildConfig(values) {
+    const bucket = cleanValue(values.bucket);
+    const accessKeyId = cleanValue(values.accessKeyId);
+    const secretAccessKey = cleanValue(values.secretAccessKey);
+    const endpoint = cleanValue(values.endpoint)?.replace(/\/+$/, "");
+    const publicBaseUrl = cleanValue(values.publicBaseUrl)?.replace(/\/+$/, "");
+    if (!bucket ||
+        !accessKeyId ||
+        !secretAccessKey ||
+        !endpoint ||
+        !publicBaseUrl) {
+        return null;
+    }
+    if (!URL.canParse(endpoint) || !URL.canParse(publicBaseUrl)) {
+        return null;
+    }
+    const endpointUrl = new URL(endpoint);
+    const publicUrl = new URL(publicBaseUrl);
+    if (!["http:", "https:"].includes(endpointUrl.protocol) ||
+        !["http:", "https:"].includes(publicUrl.protocol)) {
+        return null;
+    }
+    return {
+        region: cleanValue(values.region) ?? "auto",
+        bucket,
+        accessKeyId,
+        secretAccessKey,
+        endpoint,
+        publicBaseUrl,
+    };
+}
+function readEnvConfig() {
+    const env = process.env;
+    return buildConfig({
+        bucket: env.S3_BUCKET || env.R2_BUCKET,
+        accessKeyId: env.S3_ACCESS_KEY_ID || env.R2_ACCESS_KEY_ID,
+        secretAccessKey: env.S3_SECRET_ACCESS_KEY || env.R2_SECRET_ACCESS_KEY,
+        endpoint: env.S3_ENDPOINT || env.R2_ENDPOINT,
+        region: env.S3_REGION || env.R2_REGION,
+        publicBaseUrl: env.S3_PUBLIC_BASE_URL || env.R2_PUBLIC_BASE_URL,
+    });
+}
+async function resolveStorageSecret(primary, fallback) {
+    const primaryValue = cleanValue(await resolveSecret(primary));
+    return primaryValue ?? cleanValue(await resolveSecret(fallback));
+}
+async function readRequestConfig() {
+    const scopedConfig = buildConfig({
+        bucket: await resolveStorageSecret("S3_BUCKET", "R2_BUCKET"),
+        accessKeyId: await resolveStorageSecret("S3_ACCESS_KEY_ID", "R2_ACCESS_KEY_ID"),
+        secretAccessKey: await resolveStorageSecret("S3_SECRET_ACCESS_KEY", "R2_SECRET_ACCESS_KEY"),
+        endpoint: await resolveStorageSecret("S3_ENDPOINT", "R2_ENDPOINT"),
+        region: await resolveStorageSecret("S3_REGION", "R2_REGION"),
+        publicBaseUrl: await resolveStorageSecret("S3_PUBLIC_BASE_URL", "R2_PUBLIC_BASE_URL"),
+    });
+    return scopedConfig ?? readEnvConfig();
+}
+async function hmac(key, message) {
+    const cryptoKey = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(message));
+}
+async function sha256(data) {
+    const buffer = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buffer).set(data);
+    return toHex(await crypto.subtle.digest("SHA-256", buffer));
+}
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function signingKey(secret, dateStamp, region) {
+    const dateKey = await hmac(new TextEncoder().encode(`AWS4${secret}`).buffer, dateStamp);
+    const regionKey = await hmac(dateKey, region);
+    const serviceKey = await hmac(regionKey, "s3");
+    return hmac(serviceKey, "aws4_request");
+}
+function encodePathSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function objectPath(config, key) {
+    return `/${config.bucket}/${key.split("/").map(encodePathSegment).join("/")}`;
+}
+async function putObject(config, key, data, contentType) {
+    const now = new Date();
+    const amzDate = now
+        .toISOString()
+        .replace(/[:-]|\.\d{3}/g, "")
+        .slice(0, 15) + "Z";
+    const dateStamp = amzDate.slice(0, 8);
+    const credentialScope = `${dateStamp}/${config.region}/s3/aws4_request`;
+    const host = new URL(config.endpoint).host;
+    const canonicalUri = objectPath(config, key);
+    const payloadHash = await sha256(data);
+    const headers = {
+        host,
+        "content-type": contentType,
+        "x-amz-content-sha256": payloadHash,
+        "x-amz-date": amzDate,
+    };
+    const signedHeaderKeys = Object.keys(headers).sort();
+    const signedHeaders = signedHeaderKeys.join(";");
+    const canonicalHeaders = signedHeaderKeys
+        .map((header) => `${header}:${headers[header]}`)
+        .join("\n") + "\n";
+    const canonicalRequest = [
+        "PUT",
+        canonicalUri,
+        "",
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join("\n");
+    const requestHash = await sha256(new TextEncoder().encode(canonicalRequest));
+    const stringToSign = [
+        "AWS4-HMAC-SHA256",
+        amzDate,
+        credentialScope,
+        requestHash,
+    ].join("\n");
+    const signature = toHex(await hmac(await signingKey(config.secretAccessKey, dateStamp, config.region), stringToSign));
+    const authorization = `AWS4-HMAC-SHA256 Credential=${config.accessKeyId}/${credentialScope}, ` +
+        `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    const response = await fetch(`${config.endpoint}${canonicalUri}`, {
+        method: "PUT",
+        headers: {
+            ...headers,
+            Authorization: authorization,
+            "Content-Length": String(data.byteLength),
+        },
+        body: data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength),
+    });
+    if (!response.ok) {
+        const detail = await response.text();
+        throw new Error(`S3 PutObject failed (${response.status}): ${detail || response.statusText}`);
+    }
+    return `${config.publicBaseUrl}/${key.split("/").map(encodePathSegment).join("/")}`;
+}
+function safeFilename(filename) {
+    const basename = filename?.split(/[\\/]/).pop()?.trim() || "attachment";
+    return (basename.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 160) || "attachment");
+}
+export const s3FileUploadProvider = {
+    id: "s3",
+    name: "S3-compatible object storage",
+    isConfigured: () => readEnvConfig() !== null,
+    isConfiguredForRequest: async () => (await readRequestConfig()) !== null,
+    upload: async ({ data, filename, mimeType }) => {
+        const config = await readRequestConfig();
+        if (!config) {
+            throw new Error("S3 object storage requires a bucket, endpoint, credentials, and public base URL");
+        }
+        const key = `uploads/${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${safeFilename(filename)}`;
+        const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+        const url = await putObject(config, key, bytes, mimeType || "application/octet-stream");
+        return { url, provider: "s3" };
+    },
+};

package/dist/file-upload/types.d.ts

@@ -3,8 +3,8 @@
  *
  * Templates call `uploadFile()` to upload a file and get back a URL.
  * The framework dispatches to whichever provider is registered (Builder.io
- * built-in, or a user-supplied one). If no provider is active, it falls back
- * to the SQL resources store — fine for dev, not recommended for production.
+ * built-in, or a user-supplied one). If no provider is active, uploads fail
+ * closed so binary payloads never get persisted as base64 in SQL.
  */
 export interface FileUploadInput {
     /** File contents. */
@@ -13,7 +13,7 @@ export interface FileUploadInput {
     filename?: string;
     /** MIME type, e.g. "image/png". */
     mimeType?: string;
-    /** Optional owner email for per-user scoping in fallback storage. */
+    /** Owner email used for request-scoped provider credentials. */
     ownerEmail?: string;
     /** Builder.io upload hint: return one stable URL while compression finishes asynchronously. */
     stableUrl?: boolean;

package/dist/file-upload/types.js

@@ -3,7 +3,7 @@
  *
  * Templates call `uploadFile()` to upload a file and get back a URL.
  * The framework dispatches to whichever provider is registered (Builder.io
- * built-in, or a user-supplied one). If no provider is active, it falls back
- * to the SQL resources store — fine for dev, not recommended for production.
+ * built-in, or a user-supplied one). If no provider is active, uploads fail
+ * closed so binary payloads never get persisted as base64 in SQL.
  */
 export {};

package/dist/onboarding/app-profile.js

@@ -14,6 +14,15 @@ const DESIGN_SYSTEM_INTELLIGENCE_CAPABILITY = {
     keySummary: "Builder Design System Intelligence",
     why: "Uses your brand and design-system guidance to keep generated work on brand.",
 };
+const FILE_UPLOAD_STORAGE_CAPABILITY = {
+    id: "file-storage",
+    label: "File uploads and storage",
+    required: false,
+    suggested: true,
+    builderIncluded: true,
+    keySummary: "Builder file storage or an S3-compatible bucket, credentials, and public base URL",
+    why: "Uploaded images and files need durable object storage so the agent can reuse them throughout a thread.",
+};
 const PROFILES = {
     analytics: {
         appId: "analytics",
@@ -381,8 +390,21 @@ export function resolveOnboardingAppId(explicit) {
 export function getOnboardingAppProfile(appId) {
     const resolvedId = resolveOnboardingAppId(appId);
     const profile = PROFILES[resolvedId] ?? FALLBACK_PROFILE;
+    const capabilities = profile.capabilities.some((capability) => capability.id === FILE_UPLOAD_STORAGE_CAPABILITY.id)
+        ? profile.capabilities.map((capability) => capability.id === FILE_UPLOAD_STORAGE_CAPABILITY.id
+            ? {
+                ...FILE_UPLOAD_STORAGE_CAPABILITY,
+                // Assets and other domain-specific profiles can still make
+                // storage required while sharing the framework-wide contract.
+                required: capability.required,
+                builderIncluded: capability.builderIncluded,
+            }
+            : { ...capability })
+        : profile.capabilities.flatMap((capability, index) => index === 0
+            ? [{ ...capability }, { ...FILE_UPLOAD_STORAGE_CAPABILITY }]
+            : [{ ...capability }]);
     return {
         ...profile,
-        capabilities: profile.capabilities.map((capability) => ({ ...capability })),
+        capabilities,
     };
 }

package/dist/onboarding/default-steps.js

@@ -7,6 +7,8 @@
  */
 import { PROVIDER_ENV_META, PROVIDER_ENV_VARS, } from "../agent/engine/provider-env-vars.js";
 import { detectEngineFromUserSecrets, isAgentEngineSettingConfigured, } from "../agent/engine/registry.js";
+import { getActiveFileUploadProviderForRequest, registerFileUploadProvider, } from "../file-upload/registry.js";
+import { s3FileUploadProvider } from "../file-upload/s3.js";
 import { canUseDeployCredentialFallbackForRequest, readDeployCredentialEnv, resolveSecret, } from "../server/credential-provider.js";
 import { getSetting } from "../settings/store.js";
 import { registerOnboardingStep } from "./registry.js";
@@ -374,13 +376,80 @@ const githubRepositoryStep = {
             readDeployCredentialEnv("GH_TOKEN"));
     },
 };
+const fileStorageStep = {
+    id: "file-storage",
+    order: 15,
+    required: false,
+    title: "File uploads and storage",
+    description: "Keep uploaded images and files available throughout the thread with Builder or S3-compatible object storage.",
+    methods: [
+        {
+            id: "builder",
+            kind: "builder-cli-auth",
+            label: "Connect Builder",
+            description: "Builder includes managed file storage alongside its AI connection.",
+            primary: true,
+            badge: "free",
+            payload: { scope: "llm" },
+        },
+        {
+            id: "s3",
+            kind: "form",
+            label: "Use custom storage keys",
+            description: "Connect AWS S3, Cloudflare R2, MinIO, or another S3-compatible bucket with a stable public base URL.",
+            payload: {
+                writeScope: "workspace",
+                saveTo: "scoped-secrets",
+                secretDescription: "S3-compatible object storage for file uploads",
+                fields: [
+                    {
+                        key: "S3_ENDPOINT",
+                        label: "Endpoint URL",
+                        placeholder: "https://s3.us-east-1.amazonaws.com",
+                    },
+                    {
+                        key: "S3_BUCKET",
+                        label: "Bucket name",
+                        placeholder: "my-uploads-bucket",
+                    },
+                    {
+                        key: "S3_ACCESS_KEY_ID",
+                        label: "Access key ID",
+                        placeholder: "AKIA...",
+                    },
+                    {
+                        key: "S3_SECRET_ACCESS_KEY",
+                        label: "Secret access key",
+                        secret: true,
+                    },
+                    {
+                        key: "S3_REGION",
+                        label: "Region",
+                        placeholder: "auto",
+                    },
+                    {
+                        key: "S3_PUBLIC_BASE_URL",
+                        label: "Public base URL",
+                        placeholder: "https://cdn.example.com",
+                    },
+                ],
+            },
+        },
+    ],
+    isComplete: async () => (await getActiveFileUploadProviderForRequest()) !== null,
+};
 let registered = false;
 /** Idempotent. Safe to call from every plugin-mount call. */
 export function registerDefaultOnboardingSteps() {
     if (registered)
         return;
     registered = true;
+    // The framework provides a generic S3/R2 implementation for the custom-key
+    // onboarding path. Templates may replace the same provider id with a
+    // domain-specific implementation after this default plugin mounts.
+    registerFileUploadProvider(s3FileUploadProvider);
     registerOnboardingStep(llmStep);
+    registerOnboardingStep(fileStorageStep);
     registerOnboardingStep(databaseStep);
     registerOnboardingStep(authStep);
     registerOnboardingStep(emailStep);

package/dist/onboarding/types.d.ts

@@ -91,6 +91,8 @@ export interface OnboardingCapability {
     label: string;
     /** Whether this capability blocks the app's normal setup. */
     required: boolean;
+    /** Show this optional capability as a recommended BYOK setup. */
+    suggested?: boolean;
     /** Whether Builder's managed connection covers this capability. */
     builderIncluded: boolean;
     /** Compact description of the key or connection the BYOK path needs. */