@agent-native/core 0.209.0-nightly-20261014153330 → 0.209.0

package/dist/server/agent-chat/plugin-options.d.ts

@@ -6,6 +6,7 @@ import type { McpActionEntryOptions } from "../../mcp-client/index.js";
 import type { ExternalAgentPolicy } from "../../mcp/external-agent-policy.js";
 import type { DatabaseToolsOption } from "../../scripts/db/tool-mode.js";
 import type { PromptExamples } from "../prompts/index.js";
+import type { AgentChatAdditionalActionsExternalSurface, ResolveAgentChatAdditionalActions } from "./additional-actions.js";
 import type { AgentChatMcpIcon, AgentChatMcpOptions } from "./mcp-options.js";
 export type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 export interface AgentChatPluginOptions {
@@ -102,6 +103,26 @@ export interface AgentChatPluginOptions {
     finalResponseGuard?: AgentLoopFinalResponseGuard;
     prepareRequest?: ProductionAgentOptions["prepareRequest"];
     resolveActionSurface?: ProductionAgentOptions["resolveActionSurface"];
+    /**
+     * Adds actions for the signed-in caller on each request, such as tools whose
+     * names are only known at runtime. Called once per run, before `tool-search`
+     * and `resolveActionSurface`, so both see the entries; `surface` says which
+     * loop is asking. Interactive chat always calls it; A2A and MCP `ask_app`
+     * call it only when listed in `additionalActionSurfaces`.
+     *
+     * Entries are treated as untrusted. One whose name is malformed, reserved by
+     * a framework, template, dev, or MCP action (even one hidden from the
+     * agent), or an `mcp__` name this caller cannot see is ignored with a
+     * warning. Descriptions are cleaned and capped, and schemas must be bounded
+     * object schemas. Every call rechecks that it runs for the caller the entry
+     * was resolved for, enforces the entry's `access` policy, and validates its
+     * arguments without type coercion. A durable background continuation keeps
+     * the turn's original names. Not called for anonymous requests, scheduled
+     * jobs, automations, or agent-team sub-agents.
+     */
+    resolveAdditionalActions?: ResolveAgentChatAdditionalActions;
+    /** Surfaces besides interactive chat that receive `resolveAdditionalActions` entries. */
+    additionalActionSurfaces?: readonly AgentChatAdditionalActionsExternalSurface[];
     leanPrompt?: boolean;
     skipFilesContext?: boolean;
     initialToolNames?: string[];

package/dist/server/agent-chat-plugin.js

@@ -173,6 +173,7 @@ import { buildSystemManifestSections, setContextXraySystemSections, } from "../a
 // `createAgentChatPlugin` below stays a thinner orchestrator.
 // ---------------------------------------------------------------------------
 import { buildSelectedA2AReceiverContext, createA2AEngineToolSurface, DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKENS, DEFAULT_DELEGATED_MAX_TOOL_RESULT_CHARS, filterAgentTools, filterMcpOnlyActions, filterPublicAgentActions, filterDirectA2AActions, filterReadOnlyActions, isSelectedA2AReceiver, shouldSelectedA2AReceiverOwnObjective, resolveInitialToolNames, runA2AAgentLoop, runMCPAgentLoop, assembleA2AFinalResponse, buildPublicAgentA2ASkills, buildAuthenticatedAgentA2ASkills, resolveArtifactBaseUrl, unverifiedA2AUserError, } from "./agent-chat/action-filters-a2a.js";
+import { normalizeAdditionalActionSurfaces, resolveAppAdditionalActions, } from "./agent-chat/additional-actions.js";
 import { createBuilderBrowserTool, createTeamTools, } from "./agent-chat/browser-team-tools.js";
 import { createDataWidgetActionEntries, createFrameworkContextEntry, createRefreshScreenEntry, createUrlTools, } from "./agent-chat/context-tools.js";
 import { _agentChatPromptSectionsForTests, buildFrameworkPrompts, buildSchemaBlock, collectFiles, corpusToolNamesTaughtByPrompt, generateActionsPrompt, generateCorpusToolsPrompt, } from "./agent-chat/framework-prompts.js";
@@ -762,6 +763,28 @@ export function createAgentChatPlugin(options) {
                     ...(toolNames ? { toolNames } : {}),
                 });
             };
+            // Every registry any surface can dispatch to a built-in implementation,
+            // pushed as each one is assembled below. App-supplied request actions
+            // may not reuse any of these names, even on a surface (lean chat, A2A,
+            // ask_app) that leaves the built-in out, or an allowlist or approval
+            // granted to that name could be redirected to app code.
+            const reservedActionRegistries = [];
+            const additionalActionsConfig = {
+                resolver: options?.resolveAdditionalActions,
+                externalSurfaces: normalizeAdditionalActionSurfaces(options?.additionalActionSurfaces),
+                isReservedName: (name) => reservedActionRegistries.some((registry) => Object.hasOwn(registry, name)),
+            };
+            // The one place a request's caller-scoped actions are resolved — the
+            // caller's MCP tools plus the app's additional actions — for chat, A2A,
+            // and ask_app alike. Call it once per run, before tool-search and
+            // surface filtering, and reuse the result for the whole run.
+            const getRequestScopedActions = async (details, registered) => {
+                const mcpEntries = await getMcpActionEntriesForPrincipal(details.ownerEmail, details.orgId);
+                return {
+                    ...mcpEntries,
+                    ...(await resolveAppAdditionalActions(additionalActionsConfig, details, { ...registered, ...mcpEntries })),
+                };
+            };
             const getJobMcpActionEntries = async (job) => {
                 const requested = job?.meta.mcpTools ?? [];
                 const toolNames = resolveBackgroundMcpToolSelection(requested, options?.backgroundMcpTools === "all");
@@ -1578,6 +1601,7 @@ export function createAgentChatPlugin(options) {
             const externalFullActions = mcpFullActions
                 ? { ...mcpOnlyActions, ...mcpFullActions }
                 : undefined;
+            reservedActionRegistries.push(templateScriptsAll, discoveredActionsAll, devScriptsForA2A, externalActions, ...(externalFullActions ? [externalFullActions] : []));
             const { mountA2A } = await import("../a2a/server.js");
             const localA2AConfig = {
                 appId: options?.appId,
@@ -1909,8 +1933,8 @@ export function createAgentChatPlugin(options) {
                     // repetition guard kills the run minutes later. A rejected `{}` call
                     // returns a schema error the model can fix on the next step, which is
                     // strictly better than a shell loop nobody can see.
-                    const requestMcpActionEntries = await getMcpActionEntriesForPrincipal(userEmail, getRequestOrgId());
-                    const a2aActions = attachToolSearch(devActive
+                    const a2aOrgId = getRequestOrgId();
+                    const a2aRegisteredActions = devActive
                         ? {
                             ...templateScripts,
                             ...resourceScripts,
@@ -1930,7 +1954,6 @@ export function createAgentChatPlugin(options) {
                             ...coreEmailTools,
                             ...coreAttachmentTools,
                             ...browserTools,
-                            ...requestMcpActionEntries,
                             ...devScriptsForA2A,
                             ...devRunCodeTool,
                         }
@@ -1955,10 +1978,18 @@ export function createAgentChatPlugin(options) {
                             ...coreEmailTools,
                             ...coreAttachmentTools,
                             ...browserTools,
-                            ...requestMcpActionEntries,
                             ...(resolvedProdCodeExec !== "off" ? runCodeTool : {}),
                             ...prodCodingTools,
-                        });
+                        };
+                    const a2aActions = attachToolSearch({
+                        ...a2aRegisteredActions,
+                        ...(await getRequestScopedActions({
+                            surface: "a2a",
+                            event: context.event,
+                            ownerEmail: userEmail,
+                            orgId: a2aOrgId,
+                        }, a2aRegisteredActions)),
+                    });
                     const a2aToolSurface = createA2AEngineToolSurface(actionsToEngineTools(a2aActions), effectiveInitialToolNames, {
                         receiverOwnsObjective,
                         // Same curated set the MCP mount serves: config names plus the
@@ -2031,6 +2062,9 @@ export function createAgentChatPlugin(options) {
                         // scope when a processor hop or alternate runner is involved.
                         ownerEmail: userEmail,
                         orgId: getRequestOrgId() ?? null,
+                        // Without it, every action with an `access` policy is refused
+                        // for lack of an application identity.
+                        appId: options?.appId,
                         executionMode: "act",
                         runId: context.taskId,
                         networkProtocol: "a2a",
@@ -2406,8 +2440,8 @@ export function createAgentChatPlugin(options) {
                         // here for the same reason as the A2A surface above: an external
                         // caller cannot nurse a shell command that misfires.
                         const devActiveMcp = isDevMode();
-                        const requestMcpActionEntries = await getMcpActionEntriesForPrincipal(getRequestUserEmail(), getRequestOrgId());
-                        const mcpActions = attachToolSearch(devActiveMcp
+                        const mcpOrgId = getRequestOrgId();
+                        const mcpRegisteredActions = devActiveMcp
                             ? {
                                 ...templateScripts,
                                 ...resourceScripts,
@@ -2420,7 +2454,6 @@ export function createAgentChatPlugin(options) {
                                 ...workspaceFilesTool,
                                 ...workspaceFileActions,
                                 ...toolActions,
-                                ...requestMcpActionEntries,
                                 ...devScriptsForA2A,
                                 ...devRunCodeTool,
                             }
@@ -2438,10 +2471,13 @@ export function createAgentChatPlugin(options) {
                                 ...workspaceFilesTool,
                                 ...workspaceFileActions,
                                 ...toolActions,
-                                ...requestMcpActionEntries,
                                 ...(resolvedProdCodeExec !== "off" ? runCodeTool : {}),
                                 ...prodCodingTools,
-                            });
+                            };
+                        const mcpActions = attachToolSearch({
+                            ...mcpRegisteredActions,
+                            ...(await getRequestScopedActions({ surface: "mcp", ownerEmail, orgId: mcpOrgId }, mcpRegisteredActions)),
+                        });
                         // Same compact initial-tool surface as interactive chat and A2A:
                         // template actions + the small framework default set stay visible
                         // on the first request; everything else (provider, MCP, extension
@@ -2492,6 +2528,7 @@ export function createAgentChatPlugin(options) {
                             actions: mcpActions,
                             ownerEmail,
                             orgId: getRequestOrgId() ?? null,
+                            appId: options?.appId,
                             executionMode: "act",
                             runId: mcpRunId,
                             networkProtocol: "mcp",
@@ -2585,6 +2622,7 @@ export function createAgentChatPlugin(options) {
             catch {
                 // Ignore — templates without sharing still work.
             }
+            reservedActionRegistries.push(httpActions);
             const { mountActionRoutes, mountWebMcpActionRoutes } = await import("./action-routes.js");
             const directoryProfile = mcpOptions.enabled
                 ? mcpOptions.directoryProfile
@@ -3320,6 +3358,7 @@ export function createAgentChatPlugin(options) {
                     : {}),
             });
             leanRunCodeToolActions = leanActions;
+            reservedActionRegistries.push(prodActions, leanActions);
             // Always build the production handler (includes resource tools + call-agent + team tools)
             // In production mode (!canToggle), resolve the owner from the request session.
             const isHostedProd = !canToggle;
@@ -3529,9 +3568,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     ? "\n\n<code-execution-mode>Full shell access is enabled (trusted mode). You have bash, read, edit, write, and run-code tools available. Use bash for file discovery, running tests and builds, and project CLIs. Use run-code for sandboxed JavaScript data processing: provider/API pagination, joins, classification, aggregation, and large-response reduction. Use tool-orchestration for short bounded fan-out or reduction over read-only tools. Use `pnpm action <name>` in bash to invoke registered app actions from the shell.</code-execution-mode>"
                     : "\n\n<code-execution-mode>Sandboxed code execution is enabled. Use tool-orchestration for short bounded fan-out, joins, and reduction over read-only tools. Use run-code when you need its broader provider/web helpers, workspace staging, or durable background execution. In either tool, authenticated calls go through the provided host globals and results should be reduced before printing.</code-execution-mode>"
                 : "";
+            const prodHandlerActions = leanPrompt ? leanActions : prodActions;
             const prodHandler = createProductionAgentHandler({
                 assertAiSetupReady: requireAgentChatAiSetup,
-                actions: leanPrompt ? leanActions : prodActions,
+                actions: prodHandlerActions,
                 systemPrompt: async (event) => {
                     const { owner, extra } = await prepareRun(event);
                     const requestActionsPrompt = resolveRequestActionsPrompt("tool");
@@ -3682,7 +3722,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         _runSendByThread.delete(threadId);
                     await onRunComplete(run, threadId, trackingSource);
                 },
-                resolveAdditionalActions: ({ ownerEmail, orgId }) => getMcpActionEntriesForPrincipal(ownerEmail, orgId),
+                resolveAdditionalActions: (details) => getRequestScopedActions({ surface: "chat", ...details }, prodHandlerActions),
                 // Resolve owner from session for usage attribution in hosted prod
                 resolveOwnerEmail: isHostedProd ? getOwnerFromEvent : undefined,
             });
@@ -3829,10 +3869,11 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 // Wire the late-binding supplier for devRunCodeTool so the bridge can
                 // call back into the fully-assembled devActions registry.
                 devRunCodeToolActions = devActions;
+                reservedActionRegistries.push(devActions);
                 devHandler = createProductionAgentHandler({
                     assertAiSetupReady: requireAgentChatAiSetup,
                     actions: devActions,
-                    resolveAdditionalActions: ({ ownerEmail, orgId }) => getMcpActionEntriesForPrincipal(ownerEmail, orgId),
+                    resolveAdditionalActions: (details) => getRequestScopedActions({ surface: "chat", ...details }, devActions),
                     systemPrompt: async (event) => {
                         const { owner, extra } = await prepareRun(event);
                         const requestActionsPrompt = resolveRequestActionsPrompt(devNative ? "tool" : "cli");

package/dist/server/better-auth-instance.js

@@ -8,7 +8,9 @@ function stringifyValue(value) {
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { getCurrentAuthEndpointContext } from "@better-auth/core/context";
 import { betterAuth, } from "better-auth";
+import { createAuthMiddleware, createEmailVerificationToken, } from "better-auth/api";
 import { bearer } from "better-auth/plugins/bearer";
 import { jwt } from "better-auth/plugins/jwt";
 import { magicLink } from "better-auth/plugins/magic-link";
@@ -19,6 +21,7 @@ import { enterpriseAuthAdaptersBuilt, getAppConfig, } from "../app-config/index.
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { getDbExec } from "../db/client.js";
 import { assertHostedRuntimeDatabase, getRuntimeDatabaseUrl, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgliteDrizzleClient, pgPoolOptions, neonPoolOptions, guardNeonPool, sharedDbPool, resolveSharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, onDbClientsClosing, } from "../db/client.js";
+import { ensureTable as ensureEmailLogTable } from "../email-catalog/log.js";
 import { CORE_CHANGE_EMAIL_CONFIRMATION_EMAIL_ID, CORE_CHANGE_EMAIL_VERIFICATION_EMAIL_ID, CORE_MAGIC_LINK_EMAIL_ID, CORE_RESET_PASSWORD_EMAIL_ID, CORE_VERIFY_SIGNUP_EMAIL_ID, } from "../email-catalog/system-emails.js";
 import { renderTransactionalEmail } from "../email-catalog/templates.js";
 import { executeIdentityRekey, rekeyIdentity, resumePendingIdentityRekeys, verifiedEmailChangeFromToken, } from "../identity/rekey.js";
@@ -80,6 +83,9 @@ async function preflightEmailIdentityRekey(oldEmail, newEmail) {
     });
 }
 export { getAuthLoginMode, resolveAuthLoginMode, resolveAuthLoginModeFromReadiness, } from "./auth-login-mode.js";
+const EXISTING_ACCOUNT_VERIFICATION_COOLDOWN_MS = 5 * 60_000;
+// Signup delivery holds its transaction, connection, and per-address lock.
+const VERIFICATION_EMAIL_TIMEOUT_MS = 10_000;
 async function flushSignupTracking() {
     try {
         await Promise.race([
@@ -1559,6 +1565,25 @@ async function createBetterAuthInstance(config) {
             });
         },
     });
+    const sendVerificationEmail = async ({ user, url, token }) => {
+        const deliveredVerifyUrl = emailAuthLinkLandingUrl(url) ?? url;
+        const emailChange = await verifiedEmailChangeFromToken(token, secret, user.email);
+        if (emailChange)
+            await preflightEmailIdentityRekey(emailChange.oldEmail, emailChange.newEmail);
+        const renderedEmail = await renderTransactionalEmail(emailChange
+            ? CORE_CHANGE_EMAIL_VERIFICATION_EMAIL_ID
+            : CORE_VERIFY_SIGNUP_EMAIL_ID, { email: user.email, verifyUrl: deliveredVerifyUrl });
+        await sendEmail({
+            to: user.email,
+            ...renderedEmail,
+            disableClickTracking: true,
+            templateId: emailChange
+                ? CORE_CHANGE_EMAIL_VERIFICATION_EMAIL_ID
+                : CORE_VERIFY_SIGNUP_EMAIL_ID,
+            authCritical: true,
+            timeoutMs: VERIFICATION_EMAIL_TIMEOUT_MS,
+        });
+    };
     const auth = betterAuth({
         basePath,
         baseURL: appUrl,
@@ -1575,6 +1600,39 @@ async function createBetterAuthInstance(config) {
             // Email verification is enabled only when a provider is ready. Without
             // one, hosted deployments keep password signup available.
             requireEmailVerification,
+            onExistingUserSignUp: requireEmailVerification
+                ? async ({ user }) => {
+                    // Duplicate signup is unauthenticated, and direct auth.api calls
+                    // such as the register route skip Better Auth's IP rate limit.
+                    // The lock makes a concurrent signup for this address wait for
+                    // this transaction, so it sees the sent row before checking.
+                    const db = getDbExec();
+                    await db.execute({
+                        sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
+                        args: [`existing-account-verification:${user.email}`],
+                    });
+                    const { rows } = await db.execute({
+                        sql: `SELECT 1 FROM email_log
+                WHERE template_id = ? AND recipient = ? AND status = 'sent' AND created_at > ?
+                LIMIT 1`,
+                        args: [
+                            CORE_VERIFY_SIGNUP_EMAIL_ID,
+                            user.email,
+                            Date.now() - EXISTING_ACCOUNT_VERIFICATION_COOLDOWN_MS,
+                        ],
+                    });
+                    if (rows.length > 0)
+                        return;
+                    const endpoint = getCurrentAuthEndpointContext();
+                    const callbackURL = typeof endpoint.body?.callbackURL === "string" &&
+                        endpoint.body.callbackURL
+                        ? endpoint.body.callbackURL
+                        : "/";
+                    const token = await createEmailVerificationToken(secret, user.email);
+                    const url = `${endpoint.context.baseURL}/verify-email?token=${token}&callbackURL=${encodeURIComponent(callbackURL)}`;
+                    await sendVerificationEmail({ user, url, token });
+                }
+                : undefined,
             sendResetPassword: async ({ user, token }) => {
                 const appBasePath = (process.env.VITE_APP_BASE_PATH ||
                     process.env.APP_BASE_PATH ||
@@ -1599,24 +1657,7 @@ async function createBetterAuthInstance(config) {
         emailVerification: {
             sendOnSignUp: requireEmailVerification,
             autoSignInAfterVerification: true,
-            sendVerificationEmail: async ({ user, url, token }) => {
-                const deliveredVerifyUrl = emailAuthLinkLandingUrl(url) ?? url;
-                const emailChange = await verifiedEmailChangeFromToken(token, secret, user.email);
-                if (emailChange)
-                    await preflightEmailIdentityRekey(emailChange.oldEmail, emailChange.newEmail);
-                const renderedEmail = await renderTransactionalEmail(emailChange
-                    ? CORE_CHANGE_EMAIL_VERIFICATION_EMAIL_ID
-                    : CORE_VERIFY_SIGNUP_EMAIL_ID, { email: user.email, verifyUrl: deliveredVerifyUrl });
-                await sendEmail({
-                    to: user.email,
-                    ...renderedEmail,
-                    disableClickTracking: true,
-                    templateId: emailChange
-                        ? CORE_CHANGE_EMAIL_VERIFICATION_EMAIL_ID
-                        : CORE_VERIFY_SIGNUP_EMAIL_ID,
-                    authCritical: true,
-                });
-            },
+            sendVerificationEmail,
             afterEmailVerification: async (user, request) => {
                 if (!request)
                     return;
@@ -1870,6 +1911,55 @@ async function createBetterAuthInstance(config) {
                 ]),
             ...enterprisePlugins,
             ...configuredPlugins,
+            {
+                id: "verification-email-delivery",
+                hooks: {
+                    before: [
+                        {
+                            matcher: (ctx) => ctx.path === "/sign-up/email" && requireEmailVerification,
+                            handler: createAuthMiddleware(async () => {
+                                // A failed delivery rolls signup back; lazy log DDL must not
+                                // leave its readiness cache pointing at a rolled-back table.
+                                await ensureEmailLogTable();
+                            }),
+                        },
+                    ],
+                },
+                init(ctx) {
+                    const emailVerification = ctx.options.emailVerification;
+                    if (!emailVerification?.sendVerificationEmail)
+                        return;
+                    const sendVerificationEmail = emailVerification.sendVerificationEmail;
+                    const deliveries = new WeakSet();
+                    emailVerification.sendVerificationEmail = (...args) => {
+                        const delivery = sendVerificationEmail(...args);
+                        if (delivery instanceof Promise)
+                            deliveries.add(delivery);
+                        return delivery;
+                    };
+                    const passwordOptions = ctx.options.emailAndPassword;
+                    const onExistingUserSignUp = passwordOptions?.onExistingUserSignUp;
+                    if (passwordOptions && onExistingUserSignUp) {
+                        passwordOptions.onExistingUserSignUp = (...args) => {
+                            const delivery = onExistingUserSignUp(...args);
+                            deliveries.add(delivery);
+                            return delivery;
+                        };
+                    }
+                    const runInBackgroundOrAwait = ctx.runInBackgroundOrAwait.bind(ctx);
+                    return {
+                        context: {
+                            runInBackgroundOrAwait(task) {
+                                // Better Auth swallows even awaited task errors; verification
+                                // must fail the request before the UI can claim mail was sent.
+                                if (task instanceof Promise && deliveries.has(task))
+                                    return task;
+                                return runInBackgroundOrAwait(task);
+                            },
+                        },
+                    };
+                },
+            },
         ],
     });
     return auth;

package/dist/server/builder-browser.d.ts

@@ -261,7 +261,6 @@ export interface BuilderAgentUploadAttachment {
     name: string;
     dataUrl: string;
     text?: string;
-    size: number;
     id: string;
 }
 export interface BuilderAgentUrlAttachment {
@@ -269,6 +268,9 @@ export interface BuilderAgentUrlAttachment {
     value: string;
 }
 export type BuilderAgentAttachment = BuilderAgentUploadAttachment | BuilderAgentUrlAttachment;
+export type BuilderAgentWireAttachment = (BuilderAgentUploadAttachment & {
+    size: number;
+}) | BuilderAgentUrlAttachment;
 export interface RunBuilderAgentArgs {
     prompt: string;
     context?: string;
@@ -279,7 +281,7 @@ export interface RunBuilderAgentArgs {
     userId?: string;
 }
 export declare const BUILDER_AGENT_CONTEXT_MAX_CHARS = 32000;
-export declare function normalizeBuilderAgentAttachments(attachments: BuilderAgentAttachment[] | undefined): BuilderAgentAttachment[] | undefined;
+export declare function normalizeBuilderAgentAttachments(attachments: BuilderAgentAttachment[] | undefined): BuilderAgentWireAttachment[] | undefined;
 export declare function normalizeBuilderAgentContext(value: unknown): string | undefined;
 export declare function buildBuilderAgentUserPrompt(prompt: string, context?: string): string;
 export interface RunBuilderAgentResult {

package/dist/server/builder-browser.js

@@ -3,7 +3,7 @@ import { getHeader, getQuery, getRequestIP, setResponseHeader, setResponseStatus
 import { ActionContractError } from "../action.js";
 import { getSetting } from "../settings/store.js";
 import { applyBuilderUtmTrackingParams } from "../shared/builder-link-tracking.js";
-import { parseBase64DataUrl } from "../shared/data-url.js";
+import { base64ByteLength, isBase64, parseBase64DataUrl, } from "../shared/data-url.js";
 import { getAuthSecret, resolveSignupTrackingIdentity, } from "./better-auth-instance.js";
 import { resolveBuilderRequestAuthorization, } from "./builder-api-auth.js";
 import { firstPublicBuilderPreviewOriginFromEnv, isLoopbackBuilderRequestHost, isTrustedBuilderRequestHost, } from "./builder-preview-origin.js";
@@ -1561,50 +1561,55 @@ const BUILDER_AGENT_UPLOAD_CONTENT_TYPES = new Set([
     "application/json",
     "text/plain",
 ]);
+function invalidAttachment(message) {
+    return new ActionContractError(message, {
+        errorCode: "invalid_attachment",
+        statusCode: 400,
+    });
+}
 export function normalizeBuilderAgentAttachments(attachments) {
     if (!attachments || attachments.length === 0)
         return undefined;
-    const normalized = attachments.map((attachment) => {
+    return attachments.map((attachment) => {
         if (attachment.type === "url") {
             let url;
             try {
                 url = new URL(attachment.value);
             }
             catch {
-                throw new Error("Builder attachment URL is malformed");
+                throw invalidAttachment("Builder attachment URL is malformed");
             }
             if (url.protocol !== "https:" && url.protocol !== "http:") {
-                throw new Error("Builder attachment URL must use http or https");
+                throw invalidAttachment("Builder attachment URL must use http or https");
             }
             return attachment;
         }
         if (!BUILDER_AGENT_UPLOAD_CONTENT_TYPES.has(attachment.contentType)) {
-            throw new Error(`Unsupported Builder attachment content type: ${attachment.contentType}`);
+            throw invalidAttachment(`Unsupported Builder attachment content type: ${attachment.contentType}`);
         }
         if (!attachment.name.trim() || !attachment.id.trim()) {
-            throw new Error("Builder upload attachments require a name and id");
-        }
-        if (!Number.isInteger(attachment.size) || attachment.size < 0) {
-            throw new Error("Builder attachment size must be a non-negative integer");
+            throw invalidAttachment("Builder upload attachments require a name and id");
         }
+        let size;
         if (attachment.contentType === "text/plain" ||
             attachment.contentType === "application/json") {
             if (attachment.text === undefined || attachment.dataUrl !== "") {
-                throw new Error("Text and JSON Builder attachments require text and an empty dataUrl");
-            }
-            if (Buffer.byteLength(attachment.text, "utf8") !== attachment.size) {
-                throw new Error("Builder attachment size does not match its text content");
+                throw invalidAttachment("Text and JSON Builder attachments require text and an empty dataUrl");
             }
+            size = Buffer.byteLength(attachment.text, "utf8");
         }
         else {
             const dataUrl = parseBase64DataUrl(attachment.dataUrl);
             if (!dataUrl || dataUrl.mediaType !== attachment.contentType) {
-                throw new Error("Image and PDF Builder attachments require a matching base64 dataUrl");
+                throw invalidAttachment("Image and PDF Builder attachments require a matching base64 dataUrl");
+            }
+            if (!isBase64(dataUrl.data)) {
+                throw invalidAttachment("Image and PDF Builder attachments require valid base64 data");
             }
+            size = base64ByteLength(dataUrl.data);
         }
-        return attachment;
+        return { ...attachment, size };
     });
-    return normalized;
 }
 export function normalizeBuilderAgentContext(value) {
     if (value == null)

package/dist/server/index.d.ts

@@ -50,6 +50,7 @@ export { createObservationalMemoryPlugin, defaultObservationalMemoryPlugin, } fr
 export { createGoogleAuthPlugin, type GoogleAuthPluginOptions, } from "./google-auth-plugin.js";
 export type { GoogleAuthMode } from "./google-auth-mode.js";
 export { createAgentChatPlugin, defaultAgentChatPlugin, loadResourcesForPrompt, type AgentChatPluginOptions, } from "./agent-chat-plugin.js";
+export type { AgentChatAdditionalActionsDetails, AgentChatAdditionalActionsExternalSurface, AgentChatAdditionalActionsSurface, ResolveAgentChatAdditionalActions, } from "./agent-chat/additional-actions.js";
 export { buildFrameworkPrompts, generateActionsPrompt, } from "./agent-chat/framework-prompts.js";
 export { refreshMcpManagerForPrincipal } from "./agent-chat/mcp-glue.js";
 export { AGENT_CHAT_STREAM_PATH, AGENT_CHAT_STREAM_TOKEN_SUFFIX, AGENT_CHAT_STREAM_TOKEN_TTL_SECONDS, createAgentChatStreamToken, isAgentChatStreamingRuntime, readAgentChatStreamBearerToken, verifyAgentChatStreamToken, type AgentChatStreamPrincipal, } from "./agent-chat-stream.js";
@@ -99,7 +100,7 @@ export { isServerlessRuntime } from "../db/client.js";
 export { BUILDER_PUBLISH_MCP_RESOURCE, canAuthorizeBuilderApiRequest, hasBuilderApiCredentialCustody, resolveBuilderApiAuthorization, resolveBuilderLegacyRequestAuthorization, resolveBuilderRequestAuthorization, type BuilderLegacyCredentialKey, type BuilderRequestAuthorization, } from "./builder-api-auth.js";
 export { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_OAUTH_SCOPE, type BuilderOAuthPermissionScope, } from "./builder-oauth.js";
 export { assertBuilderDesignSystemCodeIndexingAllowed, builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, designSystemTierUpgradeUrl, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, fetchBuilderDesignSystemDocumentCount, fetchBuilderDesignSystemRecord, fetchBuilderDesignSystemTierLimit, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, isBuilderDesignSystemReadyByCount, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemDocumentCountResult, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemRecord, type BuilderDesignSystemStatus, type BuilderDesignSystemTierLimit, type BuilderDesignSystemGitHubFile, type BuilderDesignSystemGitHubFileCollection, type BuilderDesignSystemGitHubSource, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
-export { cdnSafeOriginStatus, createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, type BuilderAgentAttachment, type BuilderAgentUploadAttachment, type BuilderAgentUrlAttachment, type BuilderProjectResult, type RunBuilderAgentResult, } from "./builder-browser.js";
+export { cdnSafeOriginStatus, createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, normalizeBuilderAgentAttachments, runBuilderAgent, type BuilderAgentAttachment, type BuilderAgentUploadAttachment, type BuilderAgentUrlAttachment, type BuilderProjectResult, type RunBuilderAgentResult, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, type FusionBranchRef, type EnsureFusionContainerResult, type SendFusionMessageResult, } from "./fusion-app.js";
 export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, type EmailAttachment, type EmailReadiness, type EmailProvider, type SendEmailArgs, } from "./email.js";
 export { defineTransactionalEmail, defineTransactionalEmails, replaceTransactionalEmails, listTransactionalEmails, getTransactionalEmail, renderTransactionalEmailPreview, renderTransactionalEmailPreviewAsync, type TransactionalEmailDefinition, type RegisteredTransactionalEmail, } from "../email-catalog/registry.js";

package/dist/server/index.js

@@ -94,7 +94,7 @@ export { isServerlessRuntime } from "../db/client.js";
 export { BUILDER_PUBLISH_MCP_RESOURCE, canAuthorizeBuilderApiRequest, hasBuilderApiCredentialCustody, resolveBuilderApiAuthorization, resolveBuilderLegacyRequestAuthorization, resolveBuilderRequestAuthorization, } from "./builder-api-auth.js";
 export { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_OAUTH_SCOPE, } from "./builder-oauth.js";
 export { assertBuilderDesignSystemCodeIndexingAllowed, builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, designSystemTierUpgradeUrl, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, fetchBuilderDesignSystemDocumentCount, fetchBuilderDesignSystemRecord, fetchBuilderDesignSystemTierLimit, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, isBuilderDesignSystemReadyByCount, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
-export { cdnSafeOriginStatus, createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, } from "./builder-browser.js";
+export { cdnSafeOriginStatus, createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, normalizeBuilderAgentAttachments, runBuilderAgent, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, } from "./fusion-app.js";
 export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, } from "./email.js";
 export { defineTransactionalEmail, defineTransactionalEmails, replaceTransactionalEmails, listTransactionalEmails, getTransactionalEmail, renderTransactionalEmailPreview, renderTransactionalEmailPreviewAsync, } from "../email-catalog/registry.js";

package/dist/shared/data-url.d.ts

@@ -9,3 +9,5 @@ export interface ParsedBase64DataUrl {
 }
 export declare function parseDataUrl(value: string): ParsedDataUrl | null;
 export declare function parseBase64DataUrl(value: string): ParsedBase64DataUrl | null;
+export declare function isBase64(data: string): boolean;
+export declare function base64ByteLength(data: string): number;

package/dist/shared/data-url.js

@@ -82,3 +82,15 @@ export function parseBase64DataUrl(value) {
         ? { mediaType: parsed.mediaType, data: parsed.data }
         : null;
 }
+export function isBase64(data) {
+    const unpadded = data.replace(/={1,2}$/, "");
+    if (!/^[A-Za-z0-9+/]*$/.test(unpadded))
+        return false;
+    return unpadded.length === data.length
+        ? data.length % 4 !== 1
+        : data.length % 4 === 0;
+}
+export function base64ByteLength(data) {
+    const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+    return Math.floor((data.length * 3) / 4) - padding;
+}

package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/attachments.md

@@ -12,7 +12,6 @@ Images and PDFs use an upload attachment with a matching base64 data URL:
   contentType: "image/webp" | "image/png" | "image/jpeg" | "image/gif" | "application/pdf",
   name: string,
   dataUrl: "data:<contentType>;base64,<BASE64_CONTENT>",
-  size: number,
   id: string
 }
 ```
@@ -26,12 +25,11 @@ Text and JSON files provide decoded contents instead of a data URL:
   name: string,
   dataUrl: "",
   text: string,
-  size: number,
   id: string
 }
 ```
 
-Set `size` to the UTF-8 byte length of `text`. Use a stable or unique `id` for each attachment.
+Send any other text-based file (Markdown, CSV, source code, plain text) as `text/plain` with its real file name, for example `notes.md`. Use a stable or unique `id` for each attachment. A malformed attachment is rejected with `invalid_attachment` and a message naming the problem; fix that attachment and retry, because an unchanged retry fails the same way.
 
 ## Public URLs
 

package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/fresh-project.md

@@ -21,14 +21,19 @@ On a browser host the host is an orchestrator, not the build environment:
    (archetype, direction, first viewport, sample-data plan, agent moments).
 2. Call `start-workspace-app-creation` on the Agent-Native Dispatch MCP
    connector (`agent-native-dispatch`). Put the brief and the design decisions
-   in `prompt`; pass an `appId`, a short `description`, the `template`, the
-   selected `resourceIds`, and source files as `attachments`
-   ([attachments.md](attachments.md)). The tool's schema describes each
-   argument. Reference resources by id; never paste whole knowledge files or
-   binary data into `prompt`, and do not assume an attachment becomes a file in
-   the generated workspace. A workbook cannot be attached (attachments take
-   images, PDF, text, and JSON): pass a bounded CSV rendering as text, or a
-   public URL, and say what was left out.
+   in `prompt`; pass an `appId`, a short `description`, and the `template`.
+   The tool's schema describes each argument. Send the Project's own text as
+   `attachments` ([attachments.md](attachments.md)), never as a summary: the
+   Project instructions as `project-instructions.md` and every knowledge file,
+   each verbatim as `text/plain`. Never paste whole knowledge files or binary
+   data into `prompt`. Attachments are model context
+   and are not copied into the generated workspace, so tell the Builder agent in
+   `prompt` to persist what the app needs: knowledge files as app resources, the
+   instructions as the in-app agent's instructions. If a file cannot be
+   reproduced verbatim (not in context, too large), say so in the brief and the
+   report; never swap in a digest silently. A workbook cannot be attached
+   (attachments take images, PDF, text, and JSON): pass a bounded CSV rendering
+   as text, or a public URL, and say what was left out.
 3. Report what Dispatch actually returned: the branch, the path, and the status.
    The browser host cannot run or inspect the app, and a returned path can 404
    until the branch merges and deploys, so the report ends at pending or

package/dist/templates/workspace-core/.agents/skills/turn-into-app/references/source-brief.md

@@ -20,7 +20,7 @@ heading; write `n/a` where a heading does not apply.
 Source and provenance: type (thread, skill, Project, spreadsheet, export), file names, ids, what was read and what was not
 Project goal: the user and the repeatable job, in one sentence
 Configuration and constraints: audience, rules, output standards, approved tools
-Knowledge sources: reference files the app ships with, by name or id
+Knowledge sources: reference files the app ships with, by name
 Repeatable workflow: the job's trigger, steps, and outcome, in the source's own words
 Inputs and outputs: what comes in, what the user gets back, fixed output shapes
 Judgment and review points: 1-3 agent moments, each tied to the object it acts on; what the user confirms
@@ -38,7 +38,7 @@ App design: archetype, direction, first-viewport sketch, sample-data plan
 
 - Name the latest successful, repeatable job. A walkthrough of one example is
   evidence for the job, not the job.
-- Keep references bounded: a file name, URL, resource id, or short summary
+- Keep references bounded: a file name, URL, or short summary
   instead of a pasted document. No secrets, credentials, or customer data.
 - Corrections the user made in the source are product rules. Record each one
   as an invariant.