@hed-hog/core 0.0.400 → 0.0.402

package/src/file/file.service.ts

@@ -1,4 +1,5 @@
 import {
+  DeleteObjectCommand,
   GetBucketNotificationConfigurationCommand,
   GetObjectCommand,
   HeadBucketCommand,
@@ -25,13 +26,15 @@ import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
 import { PrismaService } from '@hed-hog/api-prisma';
 import {
   BadRequestException,
+  ConflictException,
   ForbiddenException,
   forwardRef,
   Inject,
   Injectable,
   Logger,
   NotFoundException,
-  OnModuleInit
+  OnModuleInit,
+  ServiceUnavailableException
 } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 import { createHash } from 'crypto';
@@ -56,10 +59,15 @@ import {
 } from './image-optimization.service';
 import {
   AbstractProvider,
+  MultipartUploadPart,
+  supportsDirectUpload,
   supportsServerSideCopy,
 } from './provider/abstract.provider';
 import { ProviderFactory } from './provider/provider.factory';
 
+/** Códigos de erro do S3/Spaces que indicam indisponibilidade passageira, não arquivo ruim. */
+const STORAGE_UNAVAILABLE_CODES = ['SlowDown', 'ServiceUnavailable', 'InternalError', 'RequestTimeout'];
+
 type ResolvedProvider = {
   provider: AbstractProvider;
   providerId: number;
@@ -78,6 +86,49 @@ const PROVIDER_CACHE_TTL_MS = Math.max(
   Number(process.env.FILE_PROVIDER_CACHE_TTL_MS ?? 30_000),
 );
 
+/** Upload direto em partes: mínimo de 16 MiB por parte e até 9000 partes (regra do Studio). */
+export const DIRECT_UPLOAD_MIN_PART_BYTES = 16 * 1024 * 1024;
+export const DIRECT_UPLOAD_MAX_PARTS = 9000;
+/** Validade do token e das URLs de parte: um vídeo grande em conexão lenta leva horas. */
+export const DIRECT_UPLOAD_DEFAULT_TTL_SECONDS = 86_400;
+const DIRECT_UPLOAD_TOKEN_TYPE = 'file-direct-upload';
+/**
+ * `file.size` é BIGINT no banco, e o PrismaService o devolve como number: o teto real é o
+ * maior inteiro exato de um number (~9 PB).
+ */
+const FILE_SIZE_COLUMN_MAX = Number.MAX_SAFE_INTEGER;
+
+export type DirectUploadFileInfo = {
+  originalname: string;
+  mimetype: string;
+  size: number;
+  isPrivate?: boolean;
+  createdByUserId?: number | null;
+  /** Mesmo sentido do `uploadFromPath`: o chamador já conferiu o tipo pelas regras dele. */
+  skipMimeValidation?: boolean;
+  /**
+   * O chamador já conferiu o tamanho pelas regras dele: pula a `storage-max-size`. O teto
+   * da coluna `file.size` continua valendo.
+   */
+  skipSizeValidation?: boolean;
+};
+
+export type CompleteDirectUploadInput = DirectUploadFileInfo & {
+  key: string;
+  uploadId: string;
+  destination: string;
+  parts: MultipartUploadPart[];
+  /**
+   * Confere os primeiros `bytes` do objeto gravado (ex.: sniff do tipo real). Se `check`
+   * lançar, o objeto é apagado e o erro sobe como veio; se devolver um mimetype, é ele
+   * que vai para a linha `file` (o tipo real, no lugar do declarado).
+   */
+  verifyHead?: {
+    bytes: number;
+    check: (head: Buffer) => string | void | Promise<string | void>;
+  };
+};
+
 /** Raw `?w=`/`?f=`/`?q=` query values for the public image endpoint. */
 export type ImageVariantRequest = {
   width?: number | string;
@@ -304,16 +355,37 @@ export class FileService implements OnModuleInit {
     return file;
   }
 
-  private mapStorageNotFoundError(error: any, fileId: number) {
-    const missingInStorage =
-      error?.name === 'NoSuchKey' ||
-      error?.Code === 'NoSuchKey' ||
-      error?.$metadata?.httpStatusCode === 404;
+  /**
+   * Traduz a falha do provider de storage para a resposta HTTP certa.
+   *
+   * 5xx e throttle do S3/Spaces são indisponibilidade passageira, não defeito:
+   * viram 503 com `code: STORAGE_UNAVAILABLE`, que o HttpExceptionFilter da API
+   * responde com `Retry-After` e reporta deduplicado. Sem isso, um 503 do Spaces
+   * com corpo que não é XML (ex.: `upstream connect error` do balanceador)
+   * estourava no parse do SDK como `char 'u' is not expected` e virava 500.
+   *
+   * O status vem de `$metadata.httpStatusCode`, que o SDK carimba mesmo quando a
+   * desserialização do erro falha; `$response.statusCode` cobre o resto.
+   */
+  private mapStorageError(error: any, fileId: number): never {
+    const status = error?.$metadata?.httpStatusCode ?? error?.$response?.statusCode;
+    const codes = [error?.name, error?.Code];
 
-    if (missingInStorage) {
+    if (codes.includes('NoSuchKey') || status === 404) {
       throw new NotFoundException(`File not found in storage: ${fileId}`);
     }
 
+    const unavailable =
+      (typeof status === 'number' && status >= 500) ||
+      codes.some((c) => STORAGE_UNAVAILABLE_CODES.includes(c));
+
+    if (unavailable) {
+      throw new ServiceUnavailableException(
+        { message: 'Storage temporarily unavailable', code: 'STORAGE_UNAVAILABLE' },
+        { cause: error },
+      );
+    }
+
     throw error;
   }
 
@@ -338,11 +410,15 @@ export class FileService implements OnModuleInit {
     const provider = await this.getProvider();
     const providerPath = this.resolveProviderPath(file);
 
+    // O HEAD só serve para descobrir o tamanho quando a tabela não o tem. Feito
+    // sempre, dobrava as requisições ao storage em cada segmento HLS.
     let metadata: any;
-    try {
-      metadata = await provider.metaData(providerPath);
-    } catch {
-      metadata = undefined;
+    if (file.size == null) {
+      try {
+        metadata = await provider.metaData(providerPath);
+      } catch {
+        metadata = undefined;
+      }
     }
 
     try {
@@ -353,7 +429,7 @@ export class FileService implements OnModuleInit {
         size: file.size ?? this.getFileSizeFromMetadata(metadata),
       };
     } catch (error) {
-      this.mapStorageNotFoundError(error, fileId);
+      this.mapStorageError(error, fileId);
     }
   }
 
@@ -369,16 +445,21 @@ export class FileService implements OnModuleInit {
 
     const provider = await this.getProvider();
     const providerPath = this.resolveProviderPath(file);
-    const totalSize: number = file.size ?? 0;
+    const totalSize = Number(file.size ?? 0);
 
     const resolvedStart = start ?? 0;
     const resolvedEnd = end !== undefined ? end : totalSize > 0 ? totalSize - 1 : undefined;
     const hasRange = start !== undefined;
 
-    const stream = await provider.readStream(
-      providerPath,
-      hasRange ? { start: resolvedStart, end: resolvedEnd } : undefined,
-    );
+    let stream: Awaited<ReturnType<AbstractProvider['readStream']>>;
+    try {
+      stream = await provider.readStream(
+        providerPath,
+        hasRange ? { start: resolvedStart, end: resolvedEnd } : undefined,
+      );
+    } catch (error) {
+      this.mapStorageError(error, fileId);
+    }
 
     const contentLength =
       resolvedEnd !== undefined ? resolvedEnd - resolvedStart + 1 : totalSize;
@@ -461,16 +542,7 @@ export class FileService implements OnModuleInit {
     try {
       providerBuffer = await provider.buffer(providerPath);
     } catch (error: any) {
-      const missingInStorage =
-        error?.name === 'NoSuchKey' ||
-        error?.Code === 'NoSuchKey' ||
-        error?.$metadata?.httpStatusCode === 404;
-
-      if (missingInStorage) {
-        throw new NotFoundException(`File not found in storage: ${fileId}`);
-      }
-
-      throw error;
+      this.mapStorageError(error, fileId);
     }
 
     const buffer = Buffer.from(providerBuffer);
@@ -549,6 +621,10 @@ export class FileService implements OnModuleInit {
       // Quem enviou. É o que permite recusar um `fileId` de outro usuário nas tools MCP
       // (ver `assertFileUsable`); fica nulo nos caminhos internos sem usuário.
       createdByUserId?: number | null;
+      // Grava a imagem byte a byte, sem a conversão para WebP nem o redimensionamento.
+      // Para quem entrega o arquivo a um consumidor externo que exige o formato
+      // original — o Instagram recusa WebP. O chamador já normalizou o arquivo.
+      skipImageOptimization?: boolean;
     },
   ) {
 
@@ -585,12 +661,18 @@ export class FileService implements OnModuleInit {
       fileBuffer.buffer,
     );
 
-    const optimized = await this.imageOptimizationService.optimizeBuffer(
-      fileBuffer.buffer,
-      effectiveMimetype,
-      normalizedFilename,
-      { maxWidth: resize?.maxWidth, maxHeight: resize?.maxHeight },
-    );
+    const optimized = options?.skipImageOptimization
+      ? {
+          buffer: fileBuffer.buffer,
+          mimetype: effectiveMimetype,
+          originalname: normalizedFilename,
+        }
+      : await this.imageOptimizationService.optimizeBuffer(
+          fileBuffer.buffer,
+          effectiveMimetype,
+          normalizedFilename,
+          { maxWidth: resize?.maxWidth, maxHeight: resize?.maxHeight },
+        );
 
     const normalizedFile = {
       ...fileBuffer,
@@ -635,6 +717,8 @@ export class FileService implements OnModuleInit {
       createdByUserId?: number | null;
       // Mesmo par maxWidth/maxHeight que `upload` aceita — só tem efeito em image/*.
       resize?: { maxWidth?: number; maxHeight?: number };
+      // Mesma opção de `upload`: a imagem segue o caminho de streaming, intacta.
+      skipImageOptimization?: boolean;
     },
   ) {
     if (!filePath) {
@@ -684,8 +768,9 @@ export class FileService implements OnModuleInit {
     // streaming direto do disco via provider.uploadFromPath. Isso evita carregar
     // o arquivo inteiro na RAM (fs.readFile estoura o limite de Buffer / causa OOM)
     // e habilita upload multipart no S3. A otimização de imagem só se aplica a
-    // image/*, então não há perda nesse caminho.
-    if (!mimetype.startsWith('image/')) {
+    // image/*, então não há perda nesse caminho. `skipImageOptimization` manda a
+    // imagem pelo mesmo caminho: o chamador quer os bytes exatamente como estão.
+    if (!mimetype.startsWith('image/') || metadata?.skipImageOptimization) {
       const url = await provider.uploadFromPath(destination, filePath, {
         filename: originalname,
         mimetype,
@@ -745,6 +830,292 @@ export class FileService implements OnModuleInit {
     return file;
   }
 
+  /**
+   * O storage ativo aceita upload direto em partes assinadas (S3 e Spaces)? Sem provider
+   * configurado, ou com um que não implementa, é `false` — quem oferece o caminho cai no
+   * upload pela API.
+   */
+  async supportsDirectUpload(): Promise<boolean> {
+    try {
+      return supportsDirectUpload(await this.getProvider());
+    } catch {
+      return false;
+    }
+  }
+
+  private async getDirectUploadProvider() {
+    const provider = await this.getProvider();
+    if (!supportsDirectUpload(provider)) {
+      throw new ConflictException('The file storage does not support direct uploads');
+    }
+    return provider;
+  }
+
+  /** `key` gravada pelo start: `${destination}/${uuid.ext}`, sem subpasta extra. */
+  private assertDirectUploadKey(key: string, destination: string): string {
+    const prefix = `${destination}/`;
+    const storedFilename = typeof key === 'string' && key.startsWith(prefix)
+      ? key.slice(prefix.length)
+      : '';
+
+    if (!storedFilename || storedFilename.includes('/')) {
+      throw new BadRequestException('Invalid direct upload key');
+    }
+
+    return storedFilename;
+  }
+
+  /**
+   * Abre um upload multipart direto no storage. A chave segue o mesmo formato que o
+   * `uploadFromPath` grava (`file.location` = destination, `file.path` = uuid.ext do
+   * `getFilename` do provider), então o arquivo final é servido como qualquer outro.
+   *
+   * Nada vai para o banco aqui: o estado entre as chamadas fica com quem chamou (token
+   * assinado, ver `signDirectUploadToken`) e a linha `file` só nasce no complete.
+   * Tamanho da parte com a regra do Studio: no mínimo 16 MiB e no máximo 9000 partes.
+   */
+  async startDirectUpload(destination: string, info: DirectUploadFileInfo) {
+    if (!destination) {
+      throw new BadRequestException(`No destination provided`);
+    }
+
+    const size = Number(info?.size);
+    if (!Number.isInteger(size) || size <= 0) {
+      throw new BadRequestException(`No size provided`);
+    }
+
+    // Acima disso o tamanho não cabe exato num number, e a linha não teria como ser lida.
+    if (size > FILE_SIZE_COLUMN_MAX) {
+      throw new BadRequestException(`File too large: ${size} bytes`);
+    }
+
+    const mimetype = String(info?.mimetype ?? '').trim();
+    if (!info?.skipMimeValidation && !(await this.acceptMimetypes(mimetype))) {
+      throw new BadRequestException(`Invalid file type: ${mimetype}`);
+    }
+
+    if (!info?.skipSizeValidation && !(await this.maxFileSize(size))) {
+      throw new BadRequestException(`File too large: ${size} bytes`);
+    }
+
+    const originalname = this.normalizeUploadedFilename(
+      String(info?.originalname ?? '').trim() || 'file',
+    );
+    const provider = await this.getDirectUploadProvider();
+    const key = `${destination}/${provider.getFilename(originalname)}`;
+    const uploadId = await provider.createMultipartUpload(key, mimetype || 'application/octet-stream');
+
+    const partSize = Math.max(
+      DIRECT_UPLOAD_MIN_PART_BYTES,
+      Math.ceil(size / DIRECT_UPLOAD_MAX_PARTS),
+    );
+
+    return {
+      key,
+      uploadId,
+      partSize,
+      partCount: Math.max(1, Math.ceil(size / partSize)),
+    };
+  }
+
+  /** URLs assinadas de PUT para as partes pedidas (1-based, sem repetir). */
+  async signDirectUploadParts(
+    key: string,
+    uploadId: string,
+    partNumbers: number[],
+    ttlSeconds = DIRECT_UPLOAD_DEFAULT_TTL_SECONDS,
+  ) {
+    if (!key || !uploadId) {
+      throw new BadRequestException('Invalid direct upload');
+    }
+
+    const numbers = Array.isArray(partNumbers) ? partNumbers.map(Number) : [];
+    if (
+      numbers.length === 0 ||
+      numbers.some((n) => !Number.isInteger(n) || n < 1 || n > DIRECT_UPLOAD_MAX_PARTS)
+    ) {
+      throw new BadRequestException('Invalid part numbers');
+    }
+
+    const provider = await this.getDirectUploadProvider();
+    return provider.signUploadParts(
+      key,
+      uploadId,
+      [...new Set(numbers)],
+      Math.max(60, Math.floor(ttlSeconds)),
+    );
+  }
+
+  /** Aborta o multipart (as partes já enviadas somem do bucket). Upload já fechado não é erro. */
+  async abortDirectUpload(key: string, uploadId: string): Promise<void> {
+    if (!key || !uploadId) {
+      throw new BadRequestException('Invalid direct upload');
+    }
+
+    const provider = await this.getDirectUploadProvider();
+    try {
+      await provider.abortMultipartUpload(key, uploadId);
+    } catch (error: any) {
+      const status = error?.$metadata?.httpStatusCode;
+      if (error?.name === 'NoSuchUpload' || error?.Code === 'NoSuchUpload' || status === 404) {
+        return;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fecha o multipart e registra o arquivo. Confere o que o storage gravou antes de criar
+   * a linha — tamanho pelo HeadObject (tem que bater com o declarado no start), teto
+   * `storage-max-size`, allowlist `storage-accept-mimetype` e, quando pedido, os primeiros
+   * bytes (`verifyHead`) — e apaga o objeto quando algo não confere: um upload recusado
+   * não deixa blob órfão no bucket.
+   */
+  async completeDirectUpload(input: CompleteDirectUploadInput) {
+    const { key, uploadId, destination } = input ?? ({} as CompleteDirectUploadInput);
+
+    if (!destination) {
+      throw new BadRequestException(`No destination provided`);
+    }
+    if (!uploadId) {
+      throw new BadRequestException('Invalid direct upload');
+    }
+
+    const storedFilename = this.assertDirectUploadKey(key, destination);
+
+    const parts = Array.isArray(input.parts) ? input.parts : [];
+    if (
+      parts.length === 0 ||
+      parts.some(
+        (part) =>
+          !Number.isInteger(Number(part?.partNumber)) ||
+          Number(part.partNumber) < 1 ||
+          typeof part?.etag !== 'string' ||
+          !part.etag.trim(),
+      )
+    ) {
+      throw new BadRequestException('Invalid upload parts');
+    }
+
+    const provider = await this.getDirectUploadProvider();
+
+    try {
+      await provider.completeMultipartUpload(
+        key,
+        uploadId,
+        parts.map((part) => ({ partNumber: Number(part.partNumber), etag: part.etag.trim() })),
+      );
+    } catch (error: any) {
+      const status = error?.$metadata?.httpStatusCode;
+      if (typeof status === 'number' && status >= 400 && status < 500) {
+        // Parte faltando, ETag errado, parte pequena demais: o multipart não tem conserto.
+        await this.abortDirectUpload(key, uploadId).catch(() => undefined);
+        throw new BadRequestException('The uploaded parts could not be assembled');
+      }
+      throw error;
+    }
+
+    const discard = async () => {
+      await provider.delete(key).catch((error) =>
+        this.logger.warn(`Failed to delete rejected direct upload ${key}: ${error?.message}`),
+      );
+    };
+
+    const declaredSize = Number(input.size);
+    const storedSize = this.getFileSizeFromMetadata(await provider.metaData(key));
+
+    if (storedSize === undefined || storedSize !== declaredSize) {
+      await discard();
+      throw new BadRequestException(
+        `Stored size (${storedSize ?? 'unknown'} bytes) differs from the declared size (${declaredSize} bytes)`,
+      );
+    }
+
+    if (
+      storedSize > FILE_SIZE_COLUMN_MAX ||
+      (!input.skipSizeValidation && !(await this.maxFileSize(storedSize)))
+    ) {
+      await discard();
+      throw new BadRequestException(`File too large: ${storedSize} bytes`);
+    }
+
+    let mimetype = String(input.mimetype ?? '').trim();
+
+    if (input.verifyHead) {
+      try {
+        const verified = await input.verifyHead.check(
+          await provider.readHead(key, input.verifyHead.bytes),
+        );
+        if (typeof verified === 'string' && verified.trim()) {
+          mimetype = verified.trim();
+        }
+      } catch (error) {
+        await discard();
+        throw error;
+      }
+    }
+
+    if (!input.skipMimeValidation && !(await this.acceptMimetypes(mimetype))) {
+      await discard();
+      throw new BadRequestException(`Invalid file type: ${mimetype}`);
+    }
+
+    try {
+      return await this.prismaService.file.create({
+        data: {
+          filename: this.normalizeUploadedFilename(
+            String(input.originalname ?? '').trim() || storedFilename,
+          ),
+          path: storedFilename,
+          provider_id: this.providerId,
+          location: destination,
+          mimetype_id: await this.getMimeType(mimetype),
+          size: storedSize,
+          is_private: input.isPrivate ?? false,
+          created_by_user_id: input.createdByUserId ?? null,
+        },
+      });
+    } catch (error) {
+      await discard();
+      throw error;
+    }
+  }
+
+  /**
+   * Token opaco que carrega o estado de um upload direto entre as chamadas (sem tabela):
+   * JWT HS256 com o JWT_SECRET da API e o tipo `file-direct-upload`, como o token do
+   * `file-upload-ticket`. Quem chama põe nas claims o que precisa amarrar (marca, usuário).
+   */
+  signDirectUploadToken(
+    claims: Record<string, unknown>,
+    ttlSeconds = DIRECT_UPLOAD_DEFAULT_TTL_SECONDS,
+  ): string {
+    return this.jwtService.sign(
+      { ...claims, t: DIRECT_UPLOAD_TOKEN_TYPE },
+      {
+        secret: process.env.JWT_SECRET,
+        expiresIn: `${Math.max(1, Math.floor(ttlSeconds))}s`,
+      },
+    );
+  }
+
+  /** Claims do token de upload direto; assinatura inválida, expirado ou de outro tipo = 400. */
+  readDirectUploadToken<T extends Record<string, unknown>>(token: string): T {
+    let payload: any;
+
+    try {
+      payload = this.jwtService.verify(String(token ?? ''), { secret: process.env.JWT_SECRET });
+    } catch {
+      throw new BadRequestException('Invalid or expired upload token');
+    }
+
+    if (payload?.t !== DIRECT_UPLOAD_TOKEN_TYPE) {
+      throw new BadRequestException('Token is not a direct upload token');
+    }
+
+    return payload as T;
+  }
+
   /**
    * Mimetypes de imagem que `optimizeBuffer` devolve intactos por decisão de projeto
    * (vetor não vira bitmap, GIF animado não vira quadro único). Enfileirá-los para
@@ -843,7 +1214,7 @@ export class FileService implements OnModuleInit {
   }> {
     const { file, buffer } = await this.getBuffer(fileId);
     const currentMimetype = file.file_mimetype.name;
-    const oldSize = file.size ?? buffer.length;
+    const oldSize = Number(file.size ?? buffer.length);
 
     if (!currentMimetype.startsWith('image/')) {
       return { changed: false, oldSize, newSize: oldSize, mimetypeChanged: false };
@@ -1976,6 +2347,34 @@ export class FileService implements OnModuleInit {
     });
   }
 
+  /**
+   * Apaga um objeto de bucket avulso, com as credenciais de quem o configurou.
+   *
+   * Mesmo motivo do `headS3Object` e do `signS3Object`: o bucket e de outra
+   * library (o Studio guarda os brutos no perfil de armazenamento dele), e nao o
+   * destino ativo do core. O S3 responde 204 tambem para key inexistente, entao
+   * apagar duas vezes nao e erro.
+   */
+  async deleteS3Object(params: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    region: string;
+    bucket: string;
+    key: string;
+  }): Promise<void> {
+    const s3 = new S3Client({
+      region: params.region,
+      credentials: {
+        accessKeyId: params.accessKeyId,
+        secretAccessKey: params.secretAccessKey,
+        ...(params.sessionToken ? { sessionToken: params.sessionToken } : {}),
+      },
+    });
+
+    await s3.send(new DeleteObjectCommand({ Bucket: params.bucket, Key: params.key }));
+  }
+
   async headS3Bucket(params: {
     accessKeyId: string;
     secretAccessKey: string;

package/src/file/mcp-file-source.schema.ts

@@ -35,7 +35,7 @@ export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
   uploadId: {
     type: 'number',
     description:
-      'ID returned by core.files.create-upload-url or core.files.upload.init, after the binary has been uploaded. Use this to send a file that is on disk without putting its bytes in the conversation.',
+      'ID returned by core.files.create-upload-url (after the PUT) or core.files.upload.init (after every chunk was sent with core.files.upload.append). The upload is completed automatically, so core.files.upload.complete is optional here.',
   },
   fileUrl: {
     type: 'string',
@@ -45,7 +45,7 @@ export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
   fileBase64: {
     type: 'string',
     description:
-      'Base64-encoded content, sent inline. Only for small files (about 256kb): base64 of anything larger overflows the model output limit. Requires fileName and mimeType.',
+      'Base64-encoded content, sent inline. Only for small files (about 256kb): base64 of anything larger overflows the model output limit; use core.files.upload.init for larger files instead of giving up. Requires fileName and mimeType.',
   },
   fileName: {
     type: 'string',
@@ -72,9 +72,12 @@ export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
  * `storage-max-size`, e é ele que aparece na mensagem de erro.
  */
 export const FILE_SOURCE_DESCRIPTION = [
-  'Exactly one file source is required: fileId, uploadId, fileUrl or fileBase64.',
-  'Prefer fileId; use fileBase64 only for files of a few hundred kilobytes, since the encoded content has to fit in a single tool call.',
-  'To send a local file without putting it in the conversation, call core.files.create-upload-url, PUT the binary to the URL it returns, call core.files.upload.complete, and pass the resulting fileId here.',
+  'Exactly one file source is required: fileId, uploadId, fileUrl or fileBase64. Pick the first that fits:',
+  '(1) file already in storage: fileId.',
+  '(2) file publicly reachable on the internet: fileUrl.',
+  '(3) client can make HTTP requests to the Hub API host (e.g. a local CLI agent): core.files.create-upload-url, PUT the bytes to the returned url, then pass the uploadId (or the fileId from core.files.upload.complete). Fastest.',
+  '(4) client runs in a network-restricted sandbox (e.g. claude.ai), or the PUT fails with host_not_allowed, 403 or a network error: core.files.upload.init, then core.files.upload.append for each chunk (index 0..totalChunks-1, chunkBase64 of at most chunkBytes raw bytes as returned by init), then pass the uploadId (or the fileId from core.files.upload.complete). Nothing leaves the MCP connection, and it works up to the storage max size; generate the chunks programmatically in the sandbox (split the file, print the base64 of each chunk) instead of typing base64 by hand.',
+  '(5) small file (about 256kb or less): fileBase64 inline.',
   'Every path enforces the storage-accept-mimetype and storage-max-size settings (10mb by default).',
 ].join(' ');