deepspace 0.12.0 → 0.13.0

package/dist/worker.d.ts

@@ -2882,31 +2882,82 @@ declare function applyAiToolDefaults(toolName: string, params: Record<string, un
 declare const BUILT_IN_TOOLS: ToolSchema[];
 
 /**
- * App-files limits and failure reading, shared by every caller of the files
- * API: the browser hook (`client/storage/useR2Files.ts`), the CLI
- * (`cli/lib/app-files-api.ts`), and the docs that quote them.
- *
- * The ceiling is not a product decision made here — it is what the transport
- * physically allows. An upload crosses Cloudflare's request-body limit before
- * any worker code runs, and the platform worker then reads the whole body into
- * a ~128 MiB isolate before writing it to R2. So an oversized upload does not
- * fail as a friendly JSON error; it fails as a raw Cloudflare HTML page that
- * every caller here used to feed straight into `JSON.parse` and report as
- * "Unexpected token '<' … is not valid JSON". That is the bug this module
- * exists to make impossible.
+ * App-files limits, chunk planning, and failure reading — shared by every
+ * caller of the files API: the browser hook (`client/storage/useR2Files.ts`),
+ * the CLI (`cli/lib/app-files-api.ts`), the server handler
+ * (`server/utils/scoped-r2-files.ts`), and the docs that quote them.
+ *
+ * There are three numbers here and they answer three different questions.
+ * Conflating them is what produced the old 25 MiB per-file ceiling: that was
+ * never a product decision, it was the size of one HTTP request leaking out as
+ * a rule about files. A request is bounded by physics — Cloudflare rejects an
+ * oversized body before any worker runs, and the worker's isolate is ~128 MiB.
+ * A FILE is not, once it travels as a sequence of bounded requests.
+ *
+ * The other half of this module is failure reading. An upload refused at the
+ * edge answers with a Cloudflare HTML page, which every caller used to feed
+ * straight into `JSON.parse` and report as "Unexpected token '<' … is not
+ * valid JSON". `describeFilesFailure` exists to make that impossible.
  */
 /**
  * The largest single file the app-files API accepts.
  *
- * Enforced by the shared upload handler (`server/utils/scoped-r2-files.ts`),
- * which is the only place it is a real limit — above it the platform worker
- * risks exhausting its isolate while holding the decoded file and the
- * multipart envelope together. Callers also check it locally, but only so the
- * failure is named early; skipping the client check cannot widen what is
- * accepted. Well above it (~100 MB) Cloudflare rejects the request before the
- * worker runs at all, which is why callers must read failures as text first.
+ * Reachable only through the multipart transport: a file above
+ * {@link UPLOAD_PART_BYTES} is uploaded as a sequence of parts, so no request
+ * and no isolate ever holds more than one part. Enforced by the shared handler
+ * (`server/utils/scoped-r2-files.ts`) twice — once at init against the
+ * declared total, so an impossible upload fails before a byte moves, and again
+ * at complete against the assembled object, because the declared total is
+ * client-supplied. Callers check it locally too, but only to fail early;
+ * skipping the client check cannot widen what is accepted.
  */
 declare const MAX_APP_FILE_BYTES: number;
+/**
+ * The most any ONE request body may carry — a whole small file on the
+ * single-request path, or one part on the multipart path.
+ *
+ * This is the transport's real physical bound, and the only thing 25 MiB ever
+ * meant. Above it the worker risks exhausting its isolate holding the body;
+ * well above it (~100 MB) Cloudflare refuses the request before the worker
+ * runs at all, which is why callers must read failures as text first.
+ */
+declare const MAX_UPLOAD_REQUEST_BYTES: number;
+/**
+ * The part size clients chunk at, and the threshold above which they must.
+ *
+ * Below the {@link MAX_UPLOAD_REQUEST_BYTES} bound with headroom for the
+ * request envelope, and comfortably inside R2's own part rules: parts must be
+ * at least 5 MiB and every non-final part must be exactly the same size
+ * (R2 errors 10011 / 10048). The server advertises this at init — a client
+ * chunks at the size it is told, not at this constant, so the number can move
+ * without stranding older callers mid-upload.
+ */
+declare const UPLOAD_PART_BYTES: number;
+/**
+ * The highest part number the server accepts.
+ *
+ * The handler holds no per-session state, so this — not the declared total —
+ * is what bounds an in-flight upload. It is computed against
+ * {@link UPLOAD_PART_BYTES}, which is why the server refuses a part larger
+ * than that even though a whole small file may be 25 MiB: admitting 25 MiB
+ * parts would make the real in-flight bound 52 × 25 MiB = 1300 MiB while the
+ * advertised ceiling stayed 1 GiB. With both numbers agreeing, a session's
+ * worst case is 52 × 20 MiB = 1040 MiB — the ceiling plus one part.
+ *
+ * R2 allows 10,000 parts, so this is far inside what the API permits.
+ */
+declare const MAX_UPLOAD_PARTS: number;
+/**
+ * The largest single file a deploy may ship as a static asset.
+ *
+ * Cloudflare Static Assets refuses anything larger, so this is a hard edge of
+ * the platform rather than a policy dial — which is why the CLI may check it
+ * locally. It lives here so the deploy worker and the CLI cannot drift; the
+ * per-DEPLOY total is deliberately NOT here, because it is env-configurable
+ * per environment and only the server can know it.
+ */
+declare const MAX_DEPLOY_ASSET_FILE_BYTES: number;
+declare function formatBytes(bytes: number): string;
 
 /**
  * Shared Scoped R2 Files Handler
@@ -2920,10 +2971,29 @@ declare const MAX_APP_FILE_BYTES: number;
  * The security invariants are enforced here once — not per-worker.
  *
  * Routes:
- *   POST   /api/files/upload  → upload (prefix + generated key)
- *   GET    /api/files          → list   (prefix + optional user prefix)
- *   GET    /api/files/:key     → download (validated against prefix)
- *   DELETE /api/files/:key     → delete   (validated against prefix)
+ *   POST   /api/files/upload              → upload one file in one request
+ *   POST   /api/files/multipart           → begin a chunked upload
+ *   PUT    /api/files/multipart/part      → send one part
+ *   POST   /api/files/multipart/complete  → assemble the parts
+ *   DELETE /api/files/multipart           → abandon a chunked upload
+ *   GET    /api/files                     → list   (prefix + optional user prefix)
+ *   GET    /api/files/:key                → download (validated against prefix)
+ *   DELETE /api/files/:key                → delete   (validated against prefix)
+ *
+ * ## One transport discipline
+ *
+ * Both upload paths obey the rule the deploy asset transport established
+ * (`docs/projects/2026-08-05-deploy-asset-transport/README.md`): nothing here
+ * ever holds more than one bounded request in memory. The single-request path
+ * exists so a small file still costs one round trip; above
+ * {@link UPLOAD_PART_BYTES} a file travels as parts, each streamed into R2
+ * through a `FixedLengthStream` with a required `Content-Length`. That is why
+ * a 1 GiB file is admissible in a ~128 MiB isolate.
+ *
+ * Validation is identical on both paths and on both mounts, because it lives
+ * here: the prefix scoping, the traversal check, the MIME refusals, and both
+ * size bounds. A hand-rolled request that skips every client guard reaches
+ * exactly these checks.
  */
 
 interface ScopeContext {
@@ -2953,6 +3023,7 @@ interface ScopedR2Auth {
     userId: string | null;
 }
 type ScopedR2Handler = (request: Request, url: URL, bucket: R2Bucket, auth: ScopedR2Auth) => Promise<Response>;
+declare function isFilesVerbPath(method: string, subpath: string): boolean;
 /**
  * Create a scoped R2 files handler.
  *
@@ -5166,4 +5237,4 @@ interface AppLogsResponse {
 declare const APP_LOG_EVENT_KEYS: readonly ["id", "timestamp", "level", "eventType", "message", "source", "outcome", "request", "exception"];
 type AppLogEventKey = (typeof APP_LOG_EVENT_KEYS)[number];
 
-export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_ID_RE, APP_LOG_EVENT_KEYS, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppLogEvent, type AppLogEventKey, type AppLogsResponse, type AppMigrationIdsValidation, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, Awareness, type AwarenessState, type AwarenessStates, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, type BaseMessage, BaseRoom, CANONICAL_APP_IDENTITY_MIGRATION_ID, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CLIENT_LOG_MARKER, CONVERSATION_SCHEMAS, COST_RATES, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type ClientErrorKind, type ClientErrorReport, type ClientMessage, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ComposioToolsOptions, type ConnectionAttachment, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEEPSPACE_AGENT_PROFILES, DEEPSPACE_AI_DEFAULTS, DEEPSPACE_AI_MODELS, DEEPSPACE_MODEL_CATALOG_PROVENANCE, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_QUERY_LIMIT, DEPLOYED_APPS_DEFAULTS, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DeepSpaceAIEnv, type DeepSpaceAIModel, type DeepSpaceAIModelId, type DeepSpaceAIOptions, type DeepSpaceAIProvider, type DeepSpaceAgentDiagnosticContext, DeepSpaceAgentModelError, type DeepSpaceAgentProfile, DeepSpaceAgentProfileError, type DeepSpaceAgentProfileId, type DeepSpaceAgentStream, type DeepSpaceAgentStreamOptions, type DeepSpaceAgentSupport, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DeepSpaceDocumentationRouteEnv, type DeepSpaceDocumentationRouteOptions, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type HandlerContext, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, LOG_LEVELS, type LogLevel, MAX_APP_FILE_BYTES, MESSAGES_SCHEMA, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MessageHandlers, type MsgType, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type ProtocolMessage, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, REGISTRY_INSTANCE, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, RESOURCE_ID_RE, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_DEFAULT, RecordRoom, type RecordRoomConfig, RegistryClientError, type ResolvedColumn, type ResolvedDeepSpaceAgentModel, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, STRICT_APP_ID_RE, SYSTEM_COLLECTIONS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotResult, type ServerMessage, type SharedConnection, type StoredRecord, type Summarizer, type SyncResult, TEST_ACCOUNT_EMAIL_SUFFIX, type TokenDebugInfo, type ToolResult, type ToolSchema, USERS_COLUMNS, type User, type UserAttachment, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applyAiToolDefaults, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, buildCronContext, buildTableSelect, buildUiParts, callRegistry, canCreate, canDelete, canRead, canUpdate, capToolResultSize, captureScreenshot, checkFieldPermissions, clientBuild, coerceValue, collectionTableName, columnId, composioTools, computeDoMigration, computeHmacHex, createChat, createDecoder, createDeepSpaceAI, createDeepSpaceAuth, createEncoder, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deepSpaceAgentErrorSummary, deleteChatCascade, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, enqueueJob, getChat, getDeepSpaceAIModel, getGlobalDOSchemas, getGlobalDOType, getMessageType, getRolePermissions, handleAwarenessMessage, handleClientErrorReport, handleSyncMessage, hasContent, isAutoProvision, isOwner, isTestAccountClaims, isTestAccountEmail, isTestAccountTier, lintSchema, listDeepSpaceAgentModels, loadMessages, makeDefaultSummarizer, matchOrigin, meterAi, meterUsage, meterVectorize, noopPermissionContext, parseQuotaLimit, platformCorsPatterns, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, readVarUint, readVarUint8Array, registerClientErrorRoute, registerDeepSpaceDocumentation, registryErrorJson, registryStub, resolveAppName, resolveColumn, resolveDeepSpaceAgentModel, rowToData, runMigrations, serverBuild, streamDeepSpaceAgent, timingSafeEqualHex, timingSafeEqualStrings, toUint8Array, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppMigrationIds, validateAppName, validateBindingManifest, validateDoManifest, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema, writeVarUint, writeVarUint8Array };
+export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_ID_RE, APP_LOG_EVENT_KEYS, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppLogEvent, type AppLogEventKey, type AppLogsResponse, type AppMigrationIdsValidation, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, Awareness, type AwarenessState, type AwarenessStates, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, type BaseMessage, BaseRoom, CANONICAL_APP_IDENTITY_MIGRATION_ID, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CLIENT_LOG_MARKER, CONVERSATION_SCHEMAS, COST_RATES, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type ClientErrorKind, type ClientErrorReport, type ClientMessage, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, type ComposioToolsOptions, type ConnectionAttachment, type ConvMemberData, type ConvMessageData, type ConvReactionData, type ConvReadCursorData, type ConvVoteData, type ConversationStateData, type CronContext, type CronExecution, CronRoom, type CronRoomConfig, type CronTask, type CustomBinding, type CustomBindingManifest, DEEPSPACE_AGENT_PROFILES, DEEPSPACE_AI_DEFAULTS, DEEPSPACE_AI_MODELS, DEEPSPACE_MODEL_CATALOG_PROVENANCE, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_QUERY_LIMIT, DEPLOYED_APPS_DEFAULTS, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DeepSpaceAIEnv, type DeepSpaceAIModel, type DeepSpaceAIModelId, type DeepSpaceAIOptions, type DeepSpaceAIProvider, type DeepSpaceAgentDiagnosticContext, DeepSpaceAgentModelError, type DeepSpaceAgentProfile, DeepSpaceAgentProfileError, type DeepSpaceAgentProfileId, type DeepSpaceAgentStream, type DeepSpaceAgentStreamOptions, type DeepSpaceAgentSupport, type DeepSpaceAuth, type DeepSpaceAuthConfig, type DeepSpaceDocumentationRouteEnv, type DeepSpaceDocumentationRouteOptions, type DirectoryCommunityData, type DirectoryConversationData, type DirectoryMembershipData, type DirectoryPostData, type DoMigrationDirective, type DoMigrationPlan, type ExistingDOBinding, GLOBAL_DO_TYPES, GLOBAL_DO_TYPE_NAMES, type GameInput, GameRoom, type GameRoomConfig, type GetActionData, type GlobalDOType, type HandlerContext, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, LOG_LEVELS, type LogLevel, MAX_APP_FILE_BYTES, MAX_DEPLOY_ASSET_FILE_BYTES, MAX_UPLOAD_PARTS, MAX_UPLOAD_REQUEST_BYTES, MESSAGES_SCHEMA, MSG, MSG_AWARENESS, MSG_SYNC, MSG_SYNC_STEP1, MSG_SYNC_STEP2, MSG_SYNC_UPDATE, MSG_YJS_AWARENESS, MSG_YJS_SYNC, type MessageHandlers, type MsgType, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type ProtocolMessage, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, REGISTRY_INSTANCE, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, RESOURCE_ID_RE, ROLE_ADMIN, ROLE_ANONYMOUS, ROLE_DEFAULT, RecordRoom, type RecordRoomConfig, RegistryClientError, type ResolvedColumn, type ResolvedDeepSpaceAgentModel, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, STRICT_APP_ID_RE, SYSTEM_COLLECTIONS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotResult, type ServerMessage, type SharedConnection, type StoredRecord, type Summarizer, type SyncResult, TEST_ACCOUNT_EMAIL_SUFFIX, type TokenDebugInfo, type ToolResult, type ToolSchema, UPLOAD_PART_BYTES, USERS_COLUMNS, type User, type UserAttachment, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applyAiToolDefaults, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, buildCronContext, buildTableSelect, buildUiParts, callRegistry, canCreate, canDelete, canRead, canUpdate, capToolResultSize, captureScreenshot, checkFieldPermissions, clientBuild, coerceValue, collectionTableName, columnId, composioTools, computeDoMigration, computeHmacHex, createChat, createDecoder, createDeepSpaceAI, createDeepSpaceAuth, createEncoder, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deepSpaceAgentErrorSummary, deleteChatCascade, dispatch, encode, encodeAwarenessMessage, encodeSyncStep1, encodeSyncStep2, encodeUpdate, enqueueJob, formatBytes, getChat, getDeepSpaceAIModel, getGlobalDOSchemas, getGlobalDOType, getMessageType, getRolePermissions, handleAwarenessMessage, handleClientErrorReport, handleSyncMessage, hasContent, isAutoProvision, isFilesVerbPath, isOwner, isTestAccountClaims, isTestAccountEmail, isTestAccountTier, lintSchema, listDeepSpaceAgentModels, loadMessages, makeDefaultSummarizer, matchOrigin, meterAi, meterUsage, meterVectorize, noopPermissionContext, parseQuotaLimit, platformCorsPatterns, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, readVarUint, readVarUint8Array, registerClientErrorRoute, registerDeepSpaceDocumentation, registryErrorJson, registryStub, resolveAppName, resolveColumn, resolveDeepSpaceAgentModel, rowToData, runMigrations, serverBuild, streamDeepSpaceAgent, timingSafeEqualHex, timingSafeEqualStrings, toUint8Array, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppMigrationIds, validateAppName, validateBindingManifest, validateDoManifest, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema, writeVarUint, writeVarUint8Array };