@transloadit/mcp-server 0.7.4 → 0.8.1

package/dist/server.js

@@ -3,11 +3,12 @@ import { ApiError, extractFieldNamesFromTemplate, getRobotHelp, isKnownRobot, li
 import { builtinTemplateFieldsSchema } from '@transloadit/zod/v4/builtinTemplates';
 import { z } from 'zod';
 import packageJson from '../package.json' with { type: 'json' };
-import { applyBuiltinCatalog, BuiltinFieldValidationError, builtinShortcuts, loadBuiltinShortcuts, validateBuiltinFields, } from "./builtin-shortcuts.js";
+import { applyBuiltinCatalog, BuiltinFieldValidationError, builtinShortcuts, loadBuiltinShortcuts, selectBuiltinInputUrls, validateBuiltinFields, } from "./builtin-shortcuts.js";
 import { buildBearerChallenge, extractBearerToken } from "./http-helpers.js";
+import { buildRedactor, getDiagnosticsLogger } from "./logger.js";
 import { assertServerOptions } from "./options.js";
 import { mirrorSecuritySchemes } from "./tool-list.js";
-import { buildToolMeta, resolveSecuritySchemes, resolveToolAuthMode, toolMetadata, } from "./tool-metadata.js";
+import { buildToolMeta, resolveSecuritySchemes, resolveToolAuthMode, serverInstructions, toolMetadata, } from "./tool-metadata.js";
 import { describeAssemblySteps, registerAssemblyResultWidget, widgetContextMetaKey, } from "./ui/assembly-result-widget.js";
 import { buildUploadInstructions, uploadInstructionSchema } from "./upload-instructions.js";
 const defaultConsoleUrl = 'https://transloadit.com';
@@ -19,6 +20,16 @@ const maxBase64Bytes = 512_000;
 /** URL inputs beyond these limits are not downloaded to this server's disk (per call). */
 const defaultMaxUrlDownloadBytes = 1024 * 1024 * 1024;
 const defaultUrlDownloadTimeoutMs = 10 * 60 * 1000;
+/**
+ * Hosts abandon tool calls that run too long (ChatGPT after about a minute) and may retry them,
+ * creating a second Assembly. Calls that create or follow an Assembly therefore return its
+ * current state once this budget is spent; transloadit_wait_for_assembly follows it from there.
+ */
+const defaultMaxWaitMs = 45_000;
+/** Lowest request timeout handed to the SDK, so a nearly spent budget cannot fail a request. */
+const minimumSdkTimeoutMs = 10_000;
+/** Longest a status read after an early return may take. */
+const statusReadTimeoutMs = 5_000;
 const lintIssueSchema = z.object({
     path: z.string(),
     message: z.string(),
@@ -126,6 +137,7 @@ const createAssemblyInputSchema = z.object({
 const createAssemblyOutputSchema = z.object({
     status: z.enum(['ok', 'error']),
     assembly: z.unknown().optional(),
+    running: z.boolean().optional(),
     upload: z
         .object({
         status: z.enum(['none', 'uploading', 'complete']),
@@ -158,6 +170,7 @@ const waitForAssemblyInputSchema = z.object({
 const waitForAssemblyOutputSchema = z.object({
     status: z.enum(['ok', 'error']),
     assembly: z.unknown().optional(),
+    running: z.boolean().optional(),
     waited_ms: z.number().int().nonnegative().optional(),
     errors: z.array(toolMessageSchema).optional(),
     warnings: z.array(toolMessageSchema).optional(),
@@ -289,6 +302,65 @@ const buildShortcutError = (...args) => ({
     ...buildToolError(...args),
     isError: true,
 });
+/** Maps an input preparation failure to a tool error; API rejections are left to the caller. */
+const buildInputError = (error) => {
+    // API rejections (the token check) are not input mistakes; the outer handler maps them.
+    if (error instanceof ApiError)
+        throw error;
+    const message = error instanceof Error ? error.message : 'Invalid file input.';
+    if (message.startsWith('Duplicate file field')) {
+        return buildToolError('mcp_duplicate_field', message, { path: 'files' });
+    }
+    if (message.startsWith('Base64 payload exceeds')) {
+        return buildToolError('mcp_base64_too_large', message, {
+            hint: 'Use a public URL import or upload from your own machine instead.',
+        });
+    }
+    return buildToolError('mcp_invalid_args', message);
+};
+const deadlineReached = Symbol('deadlineReached');
+/** Stops input preparation from starting another download once the wait budget is spent. */
+class PreparationBudgetSpentError extends Error {
+    name = 'PreparationBudgetSpentError';
+}
+/** Settles like `promise`, or with `deadlineReached` when it is still pending after `ms`. */
+const settleWithin = async (promise, ms) => {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(resolve, ms, deadlineReached);
+    });
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/** The SDK does not export PollingTimeoutError, so it is recognized by name. */
+const isPollingTimeout = (error) => error instanceof Error && error.name === 'PollingTimeoutError';
+/** The same states the SDK's awaitAssemblyCompletion keeps polling on. */
+const runningAssemblyStates = new Set([
+    'ASSEMBLY_UPLOADING',
+    'ASSEMBLY_EXECUTING',
+    'ASSEMBLY_REPLAYING',
+]);
+const isAssemblyRunning = (assembly) => !assembly.error && typeof assembly.ok === 'string' && runningAssemblyStates.has(assembly.ok);
+/** Tells the model that the call returned early and how to follow the Assembly instead of retrying. */
+const buildStillRunningNotice = (assembly, fallbackUrl) => {
+    const assemblyUrl = isNonEmptyString(assembly.assembly_ssl_url)
+        ? assembly.assembly_ssl_url
+        : isNonEmptyString(assembly.assembly_url)
+            ? assembly.assembly_url
+            : fallbackUrl;
+    const follow = 'Follow it with transloadit_wait_for_assembly or transloadit_get_assembly_status';
+    return {
+        code: 'mcp_assembly_still_running',
+        message: 'Returned before the Assembly finished, within the time this call may wait. The Assembly keeps running.',
+        hint: assemblyUrl
+            ? `${follow} using assembly_url ${assemblyUrl}; do not create it again.`
+            : `${follow}; do not create it again.`,
+    };
+};
 const getClientName = (options) => {
     const base = options.clientName ?? `mcp-server:${packageJson.version}`;
     const suffix = options.clientSuffix;
@@ -436,22 +508,53 @@ const toAuthRejection = (options, error, credentials, scopes) => {
     }
     return undefined;
 };
+/** Matches resolveAssemblyReference: the SDK's default when the endpoint is empty. */
+const defaultAssemblyUrl = (options, assemblyId) => `${options.endpoint || 'https://api2.transloadit.com'}/assemblies/${assemblyId}`;
 /** The Assembly exists, but its status could not be read with the caller's credentials. */
-const buildCreatedAssemblyUnavailable = (options, assemblyId) => {
-    // Matches resolveAssemblyReference: the SDK's default when the endpoint is empty.
-    const assemblyUrl = `${options.endpoint || 'https://api2.transloadit.com'}/assemblies/${assemblyId}`;
+const buildCreatedAssemblyUnavailable = (options, assemblyId, describe = (assemblyUrl) => ({
+    code: 'mcp_assembly_status_unavailable',
+    message: 'The Assembly was created, but Transloadit rejected the credentials while reading its status.',
+    hint: `Reconnect if needed, then call transloadit_get_assembly_status with assembly_url ${assemblyUrl} instead of creating it again.`,
+})) => {
+    const assemblyUrl = defaultAssemblyUrl(options, assemblyId);
     return buildToolResponse({
         status: 'error',
         assembly: { assembly_id: assemblyId, assembly_ssl_url: assemblyUrl },
-        errors: [
-            {
-                code: 'mcp_assembly_status_unavailable',
-                message: 'The Assembly was created, but Transloadit rejected the credentials while reading its status.',
-                hint: `Reconnect if needed, then call transloadit_get_assembly_status with assembly_url ${assemblyUrl} instead of creating it again.`,
-            },
-        ],
+        errors: [describe(assemblyUrl)],
     }, { isError: true });
 };
+/** The creation request is still in flight after the budget; its ID is chosen by this server. */
+const buildCreationPending = (options, assemblyId, serverFiles, 
+/** Set when some of them are uploaded from the caller's sandbox. */
+expectedUploads) => buildCreatedAssemblyUnavailable(options, assemblyId, (assemblyUrl) => {
+    // An Assembly that API2 accepted only after the request was stopped never receives this
+    // call's files, so it is resumed rather than created again: another Assembly could repeat
+    // Steps that already ran, such as imports. API2 could in theory still be handling a request
+    // it received before the abort, so the hint asks for a pause first. Strict idempotency would
+    // need an API2 creation key, which does not exist; this path only runs after a request
+    // already took longer than the budget.
+    const resumeArguments = [
+        `assembly_url ${assemblyUrl}`,
+        ...(serverFiles > 0 ? ['the same files'] : []),
+        ...(expectedUploads ? [`expected_uploads ${expectedUploads}`] : []),
+    ];
+    const resume = serverFiles > 0 || expectedUploads
+        ? `. If it is still waiting for uploads (ASSEMBLY_UPLOADING), its files were never sent: resume it by calling transloadit_create_assembly with ${resumeArguments.join(' and ')}${expectedUploads ? ', which hands out new upload_instructions' : ''}`
+        : '';
+    return {
+        code: 'mcp_assembly_creation_pending',
+        message: 'Transloadit did not confirm the Assembly in time, so this server stopped sending the creation request. Transloadit may still have received it.',
+        hint: `Wait about 30 seconds, then call transloadit_get_assembly_status with assembly_url ${assemblyUrl}. Create it again only if several checks over a few minutes report that the Assembly does not exist${resume}.`,
+    };
+});
+/** Reserved upload URLs that an early return could not include yet. */
+const buildUploadUrlsPending = (assemblyUrl) => ({
+    code: 'mcp_upload_urls_pending',
+    message: 'The upload URLs were not reserved before this call returned.',
+    // The reservations this call started keep running; asking at once could reserve the files
+    // a second time instead of returning the URLs those reservations produce.
+    hint: `Wait about 30 seconds, then call transloadit_create_assembly with assembly_url ${assemblyUrl ?? 'from this result'}, the same files and upload_behavior "none" to get them.`,
+});
 /** A failed call caused by server-side credentials; an error result so strict outputs still pass. */
 const buildCredentialError = (error) => buildToolResponse({ status: 'error', errors: [error] }, { isError: true });
 /**
@@ -573,6 +676,25 @@ const mergeFieldValues = (templateFields, argFields) => {
 };
 const assemblyIdSchema = z.string().regex(/^[a-f\d]{32}$/i);
 const assemblyUrlSchema = z.url();
+/**
+ * Reads an Assembly's current status once, without outlasting the host's patience. The SDK's
+ * rate-limit backoff does not observe the abort signal, so the read is also raced against the
+ * clock; without a status in time, it returns undefined.
+ */
+const readAssemblyStatus = async (client, assemblyId) => {
+    const status = await settleWithin(
+    // Aborts after the race below gave up, so the abort never becomes the call's error.
+    client.getAssembly(assemblyId, { signal: AbortSignal.timeout(statusReadTimeoutMs + 1_000) }), statusReadTimeoutMs);
+    return status === deadlineReached ? undefined : status;
+};
+/** Answers a call that returned early when not even the Assembly's status arrived in time. */
+const buildStatusPendingResponse = (reference, fields = {}, warnings = []) => buildToolResponse({
+    status: 'ok',
+    assembly: { assembly_id: reference.assemblyId, assembly_ssl_url: reference.assemblyUrl },
+    running: true,
+    ...fields,
+    warnings: [buildStillRunningNotice({}, reference.assemblyUrl), ...warnings],
+});
 /** Production (`.com`) and development or tunnel (`.dev`) Transloadit hosts. */
 const isTransloaditHost = (hostname) => ['transloadit.com', 'transloadit.dev'].some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
 const resolveAssemblyReference = (options, args) => {
@@ -768,10 +890,12 @@ export const listOwnTools = (server) => {
 };
 export const createTransloaditMcpServer = (options = {}) => {
     assertServerOptions(options);
+    const logger = (options.logger ?? getDiagnosticsLogger()).nest('assemblies');
+    const redactError = buildRedactor([options.authSecret, options.upstreamSecret, options.mcpToken]);
     const server = new McpServer({
         name: options.serverName ?? 'Transloadit MCP',
         version: options.serverVersion ?? packageJson.version,
-    });
+    }, { instructions: serverInstructions });
     const authMode = resolveToolAuthMode(options);
     const ownTools = new Map();
     ownToolsByServer.set(server, ownTools);
@@ -807,7 +931,9 @@ export const createTransloaditMcpServer = (options = {}) => {
         }
         return buildToolResponse(payload);
     });
-    const createAssembly = register('transloadit_create_assembly', createAssemblyInputSchema, createAssemblyOutputSchema, async ({ instructions, files, attachments, fields, wait_for_completion, wait_timeout_ms, upload_concurrency, upload_chunk_size, upload_behavior, expected_uploads, assembly_url, }, extra, fieldContractValidated = false) => {
+    const createAssembly = register('transloadit_create_assembly', createAssemblyInputSchema, createAssemblyOutputSchema, async ({ instructions, files, attachments, fields, wait_for_completion, wait_timeout_ms, upload_concurrency, upload_chunk_size, upload_behavior, expected_uploads, assembly_url, }, extra, fieldContractValidated = false, 
+    // Shortcuts start the clock before loading their catalog, which counts toward the budget.
+    startedAt = performance.now()) => {
         const liveClient = createLiveClient(options, extra);
         if ('error' in liveClient)
             return liveClient.error;
@@ -816,8 +942,19 @@ export const createTransloaditMcpServer = (options = {}) => {
         if (reference && 'error' in reference)
             return reference.error;
         const tempCleanups = [];
+        // Uploads or polling that continue after the call returned early.
+        let backgroundWork;
         const warnings = [];
         let templatePathHint;
+        const maxWaitMs = options.maxWaitMs ?? defaultMaxWaitMs;
+        // Preparation (Template lookup, file inputs) runs before any Assembly exists, so failing
+        // once it used up the budget is safe to retry, unlike a host timeout after creation.
+        const preparationRemainingMs = () => Math.max(startedAt + maxWaitMs - performance.now(), 0);
+        const preparationTimeout = (reason) => buildToolError('mcp_preparation_timeout', reference
+            ? 'Preparing the files took too long, so none were added to the Assembly.'
+            : 'Preparing the Assembly took too long, so none was created.', {
+            hint: reason ? `Retrying this call is safe. ${reason}` : 'Retrying this call is safe.',
+        });
         try {
             const fileInputs = [...(files ?? []), ...toAttachmentInputs(attachments ?? [])];
             const urlInputs = fileInputs.filter((file) => file.kind === 'url');
@@ -833,7 +970,10 @@ export const createTransloaditMcpServer = (options = {}) => {
                 templatePathHint = templatePathHint ?? 'instructions.template_id';
                 let template;
                 try {
-                    template = await client.getTemplate(params.template_id);
+                    const lookup = await settleWithin(client.getTemplate(params.template_id), preparationRemainingMs());
+                    if (lookup === deadlineReached)
+                        return preparationTimeout();
+                    template = lookup;
                 }
                 catch (error) {
                     const isTemplateNotFound = (error instanceof ApiError && error.code === 'TEMPLATE_NOT_FOUND') ||
@@ -924,7 +1064,7 @@ export const createTransloaditMcpServer = (options = {}) => {
                 tokenCheck ??= client.listTemplates({ pagesize: 1 });
                 await tokenCheck;
             };
-            const prep = await prepareInputFiles({
+            const preparation = prepareInputFiles({
                 inputFiles: inputFilesForPrep,
                 params,
                 fields,
@@ -933,23 +1073,37 @@ export const createTransloaditMcpServer = (options = {}) => {
                 allowPrivateUrls: false,
                 maxBase64Bytes,
                 maxUrlDownloadBytes: options.maxUrlDownloadBytes ?? defaultMaxUrlDownloadBytes,
-                urlDownloadTimeoutMs: options.urlDownloadTimeoutMs ?? defaultUrlDownloadTimeoutMs,
-                beforeUrlDownload: credentials === 'bearer' ? verifyTokenBeforeDownload : undefined,
-            }).catch((error) => {
-                // API rejections (the token check) are not input mistakes; the outer handler maps them.
-                if (error instanceof ApiError)
-                    throw error;
-                const message = error instanceof Error ? error.message : 'Invalid file input.';
-                if (message.startsWith('Duplicate file field')) {
-                    return buildToolError('mcp_duplicate_field', message, { path: 'files' });
-                }
-                if (message.startsWith('Base64 payload exceeds')) {
-                    return buildToolError('mcp_base64_too_large', message, {
-                        hint: 'Use a public URL import or upload from your own machine instead.',
-                    });
-                }
-                return buildToolError('mcp_invalid_args', message);
+                // prepareInputFiles() takes no abort signal, so its download timeout is what stops a
+                // download once the budget is spent; a retry would otherwise run next to it. The extra
+                // second lets the budget check below answer first, with mcp_preparation_timeout. Each
+                // download gets this timeout from its own start, but beforeUrlDownload starts none
+                // after the budget, so an abandoned download ends at most one timeout after the budget
+                // (twice the budget at worst). A tighter bound needs an abort signal in the SDK, which
+                // the URL import work in API2 makes unnecessary.
+                urlDownloadTimeoutMs: Math.min(options.urlDownloadTimeoutMs ?? defaultUrlDownloadTimeoutMs, preparationRemainingMs() + 1_000),
+                // Runs before each download, so an abandoned preparation starts no further one.
+                beforeUrlDownload: async () => {
+                    if (credentials === 'bearer')
+                        await verifyTokenBeforeDownload();
+                    if (preparationRemainingMs() === 0)
+                        throw new PreparationBudgetSpentError();
+                },
             });
+            const prep = await settleWithin(preparation, preparationRemainingMs()).catch((error) => 
+            // The budget check can reject just before the deadline timer fires.
+            error instanceof PreparationBudgetSpentError ? deadlineReached : buildInputError(error));
+            if (prep === deadlineReached) {
+                // The download stops at its timeout and prepareInputFiles() removes its files; one that
+                // still finishes first returns files that nothing uploads.
+                void preparation
+                    .then((late) => Promise.all(late.cleanup.map((cleanupFile) => cleanupFile())), () => undefined)
+                    .catch((error) => {
+                    logger.warn('Removing prepared files failed: %s', redactError(error));
+                });
+                return preparationTimeout(inputFilesForPrep.some((file) => file.kind === 'url')
+                    ? 'A retry downloads the URL inputs again from the start. To have Transloadit fetch large files itself, use transloadit_create_assembly with Steps that contain an /http/import Step.'
+                    : undefined);
+            }
             if ('content' in prep) {
                 return prep;
             }
@@ -962,68 +1116,173 @@ export const createTransloaditMcpServer = (options = {}) => {
                 status: totalFiles > 0 ? 'complete' : 'none',
                 total_files: totalFiles,
             };
-            const timeout = wait_timeout_ms;
             // Files the caller uploads itself (from a sandbox) can only start once this call returns,
-            // so waiting here would just run into the timeout.
-            const outOfBandUploads = reference ? 0 : Math.max((expected_uploads ?? 0) - totalFiles, 0);
+            // so waiting here would just run into the timeout. A resumed Assembly hands them out
+            // again, e.g. after a creation request that was stopped. Whether its uploads already
+            // arrived shows only in its status, so a resume with expected_uploads does not wait
+            // either; next_steps then point to transloadit_wait_for_assembly.
+            const outOfBandUploads = Math.max((expected_uploads ?? 0) - totalFiles, 0);
             const waitForCompletion = (wait_for_completion ?? false) && outOfBandUploads === 0;
-            if (wait_for_completion && outOfBandUploads > 0) {
-                warnings.push({
-                    code: 'mcp_wait_skipped_for_uploads',
-                    message: 'Did not wait for completion because the Assembly waits for the expected uploads. Run upload_instructions, then call transloadit_wait_for_assembly.',
-                });
-            }
             const uploadBehavior = upload_behavior ?? (waitForCompletion ? 'await' : 'background');
             const uploadConcurrency = upload_concurrency;
             const chunkSize = upload_chunk_size;
+            const deadline = startedAt +
+                (waitForCompletion ? Math.min(wait_timeout_ms ?? maxWaitMs, maxWaitMs) : maxWaitMs);
+            const remainingMs = () => Math.max(deadline - performance.now(), 0);
+            // The SDK also applies this timeout to the creation request. It outlasts the deadline and
+            // the creation grace period after it, so a request timeout never fails a creation that
+            // API2 may have accepted; the deadline below bounds the call itself. Polling after an
+            // early return is not stopped separately: it ends with this timeout, a few seconds later,
+            // and the signal that could stop it would also stop uploads the Assembly still needs.
+            const timeout = Math.max(remainingMs() + statusReadTimeoutMs + 1_000, minimumSdkTimeoutMs);
+            // Every status the SDK reports, so a call that returns early still has the latest state.
+            let latest;
+            const trackProgress = (status) => {
+                latest = status;
+            };
             let assembly;
             // Set by the SDK only after API2 accepted the creation request, so a rejected request
             // (including an error body with HTTP 200) is never mistaken for an existing Assembly.
             let createdAssemblyId;
+            let resolveCreated = () => undefined;
+            const created = new Promise((resolve) => {
+                resolveCreated = resolve;
+            });
+            let work;
+            // Chosen by the SDK before the creation request is sent.
+            let creationAssemblyId;
+            // Stops a creation request (and its rate-limit retries) that outlasted the call.
+            const creationAbort = new AbortController();
+            if (reference) {
+                work = client.resumeAssemblyUploads({
+                    assemblyUrl: reference.assemblyUrl,
+                    files: filesMap,
+                    uploads: uploadsMap,
+                    waitForCompletion,
+                    timeout,
+                    uploadConcurrency,
+                    chunkSize,
+                    uploadBehavior,
+                    onAssemblyProgress: trackProgress,
+                });
+            }
+            else {
+                const creation = client.createAssembly({
+                    params,
+                    files: filesMap,
+                    uploads: uploadsMap,
+                    waitForCompletion,
+                    timeout,
+                    uploadConcurrency,
+                    chunkSize,
+                    uploadBehavior,
+                    expectedUploads: expected_uploads,
+                    onAssemblyCreated: (status) => {
+                        createdAssemblyId = status.assembly_id ?? creation.assemblyId;
+                        latest = status;
+                        resolveCreated(status);
+                    },
+                    onAssemblyProgress: trackProgress,
+                    signal: creationAbort.signal,
+                });
+                creationAssemblyId = creation.assemblyId;
+                work = creation;
+            }
+            let workSettled = true;
+            let returnedEarly = false;
             try {
-                if (reference) {
-                    assembly = await client.resumeAssemblyUploads({
-                        assemblyUrl: reference.assemblyUrl,
-                        files: filesMap,
-                        uploads: uploadsMap,
-                        waitForCompletion,
-                        timeout,
-                        uploadConcurrency,
-                        chunkSize,
-                        uploadBehavior,
-                    });
+                const outcome = await settleWithin(work, remainingMs());
+                if (outcome !== deadlineReached) {
+                    assembly = outcome;
                 }
                 else {
-                    const creation = client.createAssembly({
-                        params,
-                        files: filesMap,
-                        uploads: uploadsMap,
-                        waitForCompletion,
-                        timeout,
-                        uploadConcurrency,
-                        chunkSize,
-                        uploadBehavior,
-                        expectedUploads: expected_uploads,
-                        onAssemblyCreated: (created) => {
-                            createdAssemblyId = created.assembly_id ?? creation.assemblyId;
-                        },
+                    // Hosts abandon calls that outlast their deadline and retry them, which creates a
+                    // second Assembly. Return what is known instead; the Assembly keeps running.
+                    workSettled = false;
+                    returnedEarly = true;
+                    backgroundWork = work.then(() => undefined, (error) => {
+                        if (isPollingTimeout(error) || creationAbort.signal.aborted)
+                            return;
+                        // A creation failure within the grace period below also reaches the caller; the
+                        // extra log line is accepted to keep this handler attached before that wait.
+                        // Hosted instances keep no per-Assembly state to report this later; follow-up
+                        // status calls show the Assembly itself.
+                        logger.warn('Assembly work after an early return failed: %s', redactError(error));
                     });
-                    assembly = await creation;
+                    if (latest) {
+                        assembly = latest;
+                    }
+                    else if (reference) {
+                        // The uploads keep running, so even a rejected read must not invite a replay.
+                        const status = await readAssemblyStatus(client, reference.assemblyId).catch(() => undefined);
+                        if (!status) {
+                            // Nothing sends reserved files or sandbox files by itself; say how to get the
+                            // URLs or commands for them.
+                            const recovery = [
+                                ...(uploadBehavior === 'none' && totalFiles > 0
+                                    ? [buildUploadUrlsPending(reference.assemblyUrl)]
+                                    : []),
+                                ...(outOfBandUploads > 0
+                                    ? [
+                                        {
+                                            code: 'mcp_upload_instructions_pending',
+                                            message: 'The upload instructions were not ready before this call returned.',
+                                            // Uploads this call started still reserve their fields; with the same
+                                            // files, the next call reuses them instead of handing out commands.
+                                            hint: `Wait about 30 seconds, then call transloadit_create_assembly with assembly_url ${reference.assemblyUrl}${totalFiles > 0 ? ', the same files' : ''} and expected_uploads ${expected_uploads} to get them.`,
+                                        },
+                                    ]
+                                    : []),
+                            ];
+                            return buildStatusPendingResponse(reference, {
+                                upload: {
+                                    ...uploadSummary,
+                                    status: uploadBehavior === 'none' || totalFiles === 0 ? 'none' : 'uploading',
+                                    resumed: true,
+                                },
+                                next_steps: [
+                                    'transloadit_wait_for_assembly',
+                                    'transloadit_get_assembly_status',
+                                ],
+                            }, recovery);
+                        }
+                        assembly = status;
+                    }
+                    else {
+                        // The creation request itself is slow (or retried); give it as long as a status read.
+                        const known = await settleWithin(Promise.race([created, work]), statusReadTimeoutMs);
+                        if (known === deadlineReached) {
+                            // Without the request, nothing can create this Assembly later, so a status check
+                            // that finds no Assembly makes creating it again safe.
+                            creationAbort.abort();
+                            return creationAssemblyId
+                                ? buildCreationPending(options, creationAssemblyId, totalFiles, outOfBandUploads > 0 ? expected_uploads : undefined)
+                                : buildToolError('mcp_assembly_creation_pending', 'Creating the Assembly is taking too long.');
+                        }
+                        assembly = known;
+                    }
                 }
             }
             catch (error) {
-                // Once API2 accepted the creation request, an auth failure (a token expiring while
-                // uploads or polling run) must not reach the client as a challenge: it would refresh and
-                // replay the call, creating and billing a second Assembly.
-                if (createdAssemblyId && toAuthRejection(options, error, credentials, [])) {
-                    return buildCreatedAssemblyUnavailable(options, createdAssemblyId);
+                if (isPollingTimeout(error) && latest) {
+                    // The SDK's own polling ran out of time; the Assembly is still known and running.
+                    assembly = latest;
+                    returnedEarly = true;
                 }
-                if (isErrnoException(error) && error.code === 'ENOENT') {
-                    return buildToolError('mcp_file_not_found', 'A prepared upload is no longer available.', {
-                        hint: 'Retry with base64 or a public URL, or upload via `npx -y @transloadit/node upload`.',
-                    });
+                else {
+                    // Once API2 accepted the creation request, an auth failure (a token expiring while
+                    // uploads or polling run) must not reach the client as a challenge: it would refresh
+                    // and replay the call, creating and billing a second Assembly.
+                    if (createdAssemblyId && toAuthRejection(options, error, credentials, [])) {
+                        return buildCreatedAssemblyUnavailable(options, createdAssemblyId);
+                    }
+                    if (isErrnoException(error) && error.code === 'ENOENT') {
+                        return buildToolError('mcp_file_not_found', 'A prepared upload is no longer available.', {
+                            hint: 'Retry with base64 or a public URL, or upload via `npx -y @transloadit/node upload`.',
+                        });
+                    }
+                    throw error;
                 }
-                throw error;
             }
             if (assembly_url) {
                 uploadSummary.resumed = true;
@@ -1034,29 +1293,63 @@ export const createTransloaditMcpServer = (options = {}) => {
             else if (uploadBehavior === 'none') {
                 uploadSummary.status = 'none';
             }
-            else if (uploadBehavior === 'background') {
+            else if (uploadBehavior === 'background' ||
+                (!workSettled && assembly.ok === 'ASSEMBLY_UPLOADING')) {
                 uploadSummary.status = 'uploading';
             }
             if (isRecord(assembly.upload_urls)) {
                 uploadSummary.upload_urls = assembly.upload_urls;
             }
-            const uploadInstructions = outOfBandUploads > 0
-                ? buildUploadInstructions(assembly, outOfBandUploads, new Set([...Object.keys(filesMap), ...Object.keys(uploadsMap)]))
+            const ownFields = new Set([...Object.keys(filesMap), ...Object.keys(uploadsMap)]);
+            // A resumed Assembly may have received some uploads already, and takes more only while
+            // it waits for them; expected_uploads counts all of its uploads, as at creation.
+            // Finished uploads are listed under uploads, running ones under tus_uploads.
+            const receivedFields = new Set([
+                ...(assembly.uploads ?? []).map((upload) => upload.field),
+                ...(assembly.tus_uploads ?? []).map((upload) => upload.fieldname),
+            ].filter((field) => isNonEmptyString(field) && !ownFields.has(field)));
+            const pendingUploads = !reference
+                ? outOfBandUploads
+                : assembly.ok === 'ASSEMBLY_UPLOADING'
+                    ? Math.max(outOfBandUploads - receivedFields.size, 0)
+                    : 0;
+            const uploadInstructions = pendingUploads > 0
+                ? buildUploadInstructions(assembly, pendingUploads, new Set([...ownFields, ...receivedFields]))
                 : undefined;
-            if (outOfBandUploads > 0 && !uploadInstructions) {
+            if (wait_for_completion && uploadInstructions) {
+                warnings.push({
+                    code: 'mcp_wait_skipped_for_uploads',
+                    message: 'Did not wait for completion because the Assembly waits for the expected uploads. Run upload_instructions, then call transloadit_wait_for_assembly.',
+                });
+            }
+            if (pendingUploads > 0 && !uploadInstructions) {
                 warnings.push({
                     code: 'mcp_upload_instructions_unavailable',
                     message: 'The Assembly status has no tus_url or assembly_ssl_url to upload to.',
                 });
             }
+            const running = isAssemblyRunning(assembly);
+            if (returnedEarly && running) {
+                warnings.push(buildStillRunningNotice(assembly, reference?.assemblyUrl));
+            }
+            if (returnedEarly &&
+                uploadBehavior === 'none' &&
+                totalFiles > 0 &&
+                !uploadSummary.upload_urls) {
+                // Nothing uploads these files later, so the caller needs their reserved upload URLs.
+                const assemblyUrl = reference?.assemblyUrl ??
+                    (isNonEmptyString(assembly.assembly_ssl_url) ? assembly.assembly_ssl_url : undefined);
+                warnings.push(buildUploadUrlsPending(assemblyUrl));
+            }
             const nextSteps = uploadInstructions
                 ? ['transloadit_wait_for_assembly']
-                : waitForCompletion
+                : waitForCompletion && !running
                     ? []
                     : ['transloadit_wait_for_assembly', 'transloadit_get_assembly_status'];
             return buildToolResponse({
                 status: 'ok',
                 assembly,
+                running,
                 upload: uploadSummary,
                 upload_instructions: uploadInstructions,
                 next_steps: nextSteps,
@@ -1070,7 +1363,19 @@ export const createTransloaditMcpServer = (options = {}) => {
             throw error;
         }
         finally {
-            await Promise.all(tempCleanups.map((cleanup) => cleanup()));
+            const cleanup = async () => {
+                await Promise.all(tempCleanups.map((cleanupFile) => cleanupFile()));
+            };
+            // Uploads that continue after an early return still read the prepared files. This
+            // promise never rejects.
+            if (backgroundWork) {
+                void backgroundWork.then(cleanup).catch((error) => {
+                    logger.warn('Removing prepared files failed: %s', redactError(error));
+                });
+            }
+            else {
+                await cleanup();
+            }
         }
     });
     // Keep the generic execution path responsible for auth, uploads, waiting and widget results.
@@ -1080,6 +1385,7 @@ export const createTransloaditMcpServer = (options = {}) => {
         .strict();
     for (const { id, name } of builtinShortcuts) {
         register(name, shortcutInputSchema, createAssemblyOutputSchema, async (args, extra) => {
+            const startedAt = performance.now();
             const live = createLiveClient(options, extra, 0);
             if ('error' in live)
                 return live.error;
@@ -1107,7 +1413,22 @@ export const createTransloaditMcpServer = (options = {}) => {
                 }
                 return buildShortcutError('mcp_invalid_builtin_fields', error.message, { path: 'fields' });
             }
-            const result = await createAssembly({ ...args, fields, instructions: { template_id: template.id } }, extra, true);
+            // upload_behavior none asks for reserved upload URLs, which only the upload path hands out.
+            const inputUrls = args.upload_behavior === 'none'
+                ? undefined
+                : selectBuiltinInputUrls(template.id, [...(args.files ?? []), ...toAttachmentInputs(args.attachments ?? [])], args.expected_uploads);
+            // API2 imports eligible URLs itself (api2#10292), so the Assembly exists at once and nothing
+            // is downloaded here. A refusal is API2's to explain, so it surfaces like any other error.
+            const result = await createAssembly(inputUrls
+                ? {
+                    ...args,
+                    files: undefined,
+                    attachments: undefined,
+                    expected_uploads: undefined,
+                    fields,
+                    instructions: { template_id: template.id, input_url: inputUrls },
+                }
+                : { ...args, fields, instructions: { template_id: template.id } }, extra, true, startedAt);
             // Keep the generic tool's historical error shape while making new shortcut failures
             // recognizable to MCP clients that rely on isError instead of structuredContent.status.
             return result.structuredContent?.status === 'error' ? { ...result, isError: true } : result;
@@ -1137,25 +1458,59 @@ export const createTransloaditMcpServer = (options = {}) => {
         if ('error' in access)
             return access.error;
         const start = Date.now();
+        const maxWaitMs = options.maxWaitMs ?? defaultMaxWaitMs;
+        const budgetMs = Math.min(timeout_ms ?? maxWaitMs, maxWaitMs);
+        // Polling only reads status, so it can be stopped as soon as the budget is spent.
+        const polling = new AbortController();
+        let latest;
         let assembly;
+        let returnedEarly = false;
         try {
-            assembly = await access.client.awaitAssemblyCompletion(access.assemblyId, {
-                timeout: timeout_ms,
+            const outcome = await settleWithin(access.client.awaitAssemblyCompletion(access.assemblyId, {
+                timeout: budgetMs,
                 interval: poll_interval_ms,
                 assemblyUrl: access.assemblyUrl,
-            });
+                signal: polling.signal,
+                onAssemblyProgress: (status) => {
+                    latest = status;
+                },
+            }), budgetMs);
+            if (outcome === deadlineReached) {
+                polling.abort();
+                returnedEarly = true;
+                const status = latest ?? (await readAssemblyStatus(access.client, access.assemblyId));
+                if (!status) {
+                    return buildStatusPendingResponse({
+                        assemblyId: access.assemblyId,
+                        assemblyUrl: access.assemblyUrl ?? defaultAssemblyUrl(options, access.assemblyId),
+                    }, { waited_ms: Date.now() - start });
+                }
+                assembly = status;
+            }
+            else {
+                assembly = outcome;
+            }
         }
         catch (error) {
-            const rejection = toAuthRejection(options, error, access.credentials, toolMetadata.transloadit_wait_for_assembly.scopes);
-            if (rejection)
-                return rejection;
-            throw error;
+            if (!(isPollingTimeout(error) && latest)) {
+                const rejection = toAuthRejection(options, error, access.credentials, toolMetadata.transloadit_wait_for_assembly.scopes);
+                if (rejection)
+                    return rejection;
+                throw error;
+            }
+            assembly = latest;
+            returnedEarly = true;
         }
         const waited_ms = Date.now() - start;
+        const running = isAssemblyRunning(assembly);
         return buildToolResponse({
             status: 'ok',
             assembly,
+            running,
             waited_ms,
+            warnings: returnedEarly && running
+                ? [buildStillRunningNotice(assembly, access.assemblyUrl)]
+                : undefined,
         }, { meta: { [widgetContextMetaKey]: buildWidgetContext(options, assembly) } });
     });
     register('transloadit_list_robots', listRobotsInputSchema, listRobotsOutputSchema, ({ category, search, limit, cursor }) => {