deepspace 0.3.9 → 0.3.11

package/dist/server.d.ts

@@ -1062,6 +1062,10 @@ declare const MSG: {
     readonly CRON_PAUSE: "cron.pause";
     readonly CRON_RESUME: "cron.resume";
     readonly CRON_STATUS: "cron.status";
+    readonly JOB_ENQUEUE: "job.enqueue";
+    readonly JOB_CANCEL: "job.cancel";
+    readonly JOB_RETRY: "job.retry";
+    readonly JOB_UPDATE: "job.update";
     readonly PRESENCE_SYNC: "presence.sync";
     readonly PRESENCE_JOIN: "presence.join";
     readonly PRESENCE_LEAVE: "presence.leave";
@@ -1243,6 +1247,12 @@ type ServerMessage = BaseMessage<typeof MSG.QUERY_RESULT, {
 }> | BaseMessage<typeof MSG.CRON_STATUS, {
     tasks: unknown;
     recentHistory: unknown;
+}> | BaseMessage<typeof MSG.JOB_UPDATE, {
+    kind: 'snapshot' | 'enqueued' | 'progress' | 'succeeded' | 'failed' | 'canceled' | 'retried';
+    job?: unknown;
+    jobs?: unknown[];
+    /** Echoes the enqueue requestId when the update is the enqueue ack. */
+    requestId?: string;
 }> | BaseMessage<typeof MSG.PRESENCE_SYNC, {
     peers: unknown[];
 }> | BaseMessage<typeof MSG.PRESENCE_JOIN, {
@@ -1989,6 +1999,166 @@ declare abstract class CronRoom<E = Record<string, unknown>> extends BaseRoom<E>
     protected abstract onTask(taskName: string): void | Promise<void>;
 }
 
+/**
+ * JobRoom — Per-app durable background-job execution Durable Object.
+ *
+ * Solves the "long job dies when the response goes out" problem on
+ * Cloudflare Workers. `ctx.waitUntil` only gets 30s after a response;
+ * jobs that need minutes-to-hours live here instead: rows in SQLite,
+ * picked up by DO alarms (15-min wall budget per tick), resumable
+ * across ticks via `ctx.continue` for the rare longer cases.
+ *
+ * Lifecycle: queued → running → succeeded | failed | canceled
+ *
+ * Crash recovery: if an isolate is recycled mid-run, the row stays at
+ * `running`. On next init, rows older than ~16 min are either retried
+ * (if attempts left) or marked failed.
+ *
+ * See the abstract `onJob` method below for the subclass contract.
+ * Message types: job.*
+ */
+
+type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled';
+/**
+ * Job record exposed to `onJob` handlers and clients. Payloads are typed
+ * as `unknown` at the SDK layer; subclasses narrow via a generic param.
+ */
+interface Job<P = unknown> {
+    id: string;
+    type: string;
+    status: JobStatus;
+    payload: P;
+    result?: unknown;
+    error?: string;
+    progress?: number;
+    progressMessage?: string;
+    attempts: number;
+    maxAttempts: number;
+    enqueuedAt: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    enqueuedBy?: string | null;
+    /** Set when a previous run called `ctx.continue(state)`. */
+    resumeFrom?: unknown;
+}
+interface JobContext {
+    /** Set progress (0..1) with an optional message. Broadcasts. */
+    progress(value: number, message?: string): void;
+    /**
+     * Save a resumable checkpoint and re-run `onJob` on the next alarm
+     * with `job.resumeFrom = state`. The return value of `onJob` is
+     * ignored once `continue` has been called.
+     */
+    continue(state: unknown, options?: {
+        afterMs?: number;
+    }): void;
+    /**
+     * Fires when a JOB_CANCEL arrives while this job is running in this
+     * isolate. Cross-isolate cancels still mark the row `canceled` but
+     * can't fire this signal.
+     */
+    signal: AbortSignal;
+}
+interface JobRoomConfig {
+    /** Default for jobs enqueued without explicit `maxAttempts`. Default 1 (no auto-retry). */
+    defaultMaxAttempts?: number;
+    /** TTL for terminal rows (succeeded/failed/canceled) in ms. Default 24h. */
+    retentionMs?: number;
+    /** Job count in the initial snapshot to a new subscriber. Default 100. */
+    snapshotLimit?: number;
+    /** Delay before a failed attempt is retried, in ms. Default 1000. */
+    retryBackoffMs?: number;
+}
+declare abstract class JobRoom<E = Record<string, unknown>, P = unknown, R = unknown> extends BaseRoom<E> {
+    private initialized;
+    private readonly defaultMaxAttempts;
+    private readonly retentionMs;
+    private readonly snapshotLimit;
+    private readonly retryBackoffMs;
+    /** In-flight jobs in this isolate; lets same-isolate JOB_CANCEL fire the signal. */
+    private readonly inFlight;
+    /** Set by `ctx.continue` inside `executeJob`; reset before every run. */
+    private continueState;
+    constructor(state: DurableObjectState, env: unknown, config?: JobRoomConfig);
+    private ensureInitialized;
+    fetch(request: Request): Promise<Response>;
+    protected onConnect(ws: WebSocket, user: UserAttachment): UserAttachment;
+    protected onMessage(ws: WebSocket, user: UserAttachment, message: {
+        type: string;
+        [key: string]: unknown;
+    }): Promise<void>;
+    protected onAlarm(): Promise<void>;
+    /**
+     * One internal endpoint, `POST /enqueue`, used by the `enqueueJob`
+     * helper at the bottom of this file. The room is not meant to be
+     * reachable from the public internet; callers route through the app
+     * worker (or call `this.enqueue(...)` directly from a subclass).
+     *
+     * Subclasses overriding `onRequest` should call `super.onRequest(req)`
+     * for paths they don't handle.
+     */
+    protected onRequest(request: Request): Promise<Response>;
+    /**
+     * Synchronously persist a new job and arm the alarm. Returns the new
+     * job. This is the in-isolate path — useful for a subclass `onJob`
+     * that wants to chain follow-up work without paying a fetch hop:
+     *
+     *   protected async onJob(job: Job, ctx: JobContext) {
+     *     // ... do work ...
+     *     if (needsFollowup) this.enqueue('followup', { parent: job.id })
+     *   }
+     *
+     * Workers code that lives outside the DO isolate (HTTP routes, cron
+     * tasks, server actions) cannot call this directly — they must go
+     * through the `enqueueJob` helper at the bottom of this file, which
+     * routes via the DO's `/enqueue` HTTP endpoint.
+     */
+    enqueue(type: string, payload?: unknown, options?: {
+        maxAttempts?: number;
+        enqueuedBy?: string;
+    }): Job;
+    private insertJob;
+    private cancelJob;
+    private retryJob;
+    /**
+     * Drain due jobs in FIFO order. All due jobs share the alarm's
+     * 15-min wall budget (a CF property, not a per-job allocation).
+     */
+    private drainDueJobs;
+    private executeJob;
+    private makeContext;
+    private readStatus;
+    private scheduleNextAlarm;
+    private recoverStuckRunning;
+    private pruneExpired;
+    private getRecentJobs;
+    private getJobById;
+    /**
+     * Run a single job. Return a value for success; throw for failure
+     * (retried until attempts >= maxAttempts). Use `ctx.progress` for
+     * progress, `ctx.continue(state)` to span multiple alarms, and
+     * `ctx.signal` to honor client cancellations.
+     */
+    protected abstract onJob(job: Job<P>, ctx: JobContext): Promise<R | void> | R | void;
+}
+/**
+ * Enqueue a job from worker code that has the DO namespace. Routed by
+ * `roomId` (typically `app:<APP_NAME>`; pass different ids for sharded
+ * queues). Returns the new jobId; throws on failure.
+ *
+ *   const jobId = await enqueueJob(
+ *     env.JOB_ROOMS,
+ *     `app:${env.APP_NAME}`,
+ *     'ai-summarize',
+ *     { text },
+ *     { maxAttempts: 3 },
+ *   )
+ */
+declare function enqueueJob(namespace: DurableObjectNamespace, roomId: string, type: string, payload?: unknown, options?: {
+    maxAttempts?: number;
+    enqueuedBy?: string;
+}): Promise<string>;
+
 /**
  * DO Manifest — Dynamic Durable Object binding declarations.
  *
@@ -2713,7 +2883,7 @@ declare function handleToolsRequest(ctx: ToolsApiContext, request: Request, path
 interface JwtVerifierConfig {
     /** PEM-encoded public key (ES256) for JWT verification */
     publicKey: string;
-    /** Expected issuer (e.g. "https://auth.deep.space") */
+    /** Expected issuer (e.g. "https://auth.deep.space/api/auth") */
     issuer: string;
     /** Expected audience (usually the configured platform API URL) */
     audience?: string | string[];
@@ -3802,4 +3972,4 @@ declare class RefundError extends Error {
     constructor(message: string, status: number);
 }
 
-export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CancelSubscriptionError, type CancelSubscriptionOpts, type CancelSubscriptionResult, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, 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, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_MAX_SKEW_MS, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DebugApiContext, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, 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 InternalSignature, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlanInfo, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, type RecordContext, RecordRoom, type RecordRoomConfig, RefundError, type RefundOpts, type RefundResult, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTION_SCHEMAS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type SharedConnection, type SignInternalPayloadInput, type StoredRecord, SubscriptionAuthError, type SubscriptionContext, type SubscriptionRead, SubscriptionRequiredError, type SubscriptionStatus, type Summarizer, type TokenDebugInfo, type ToolResult, type ToolSchema, type ToolsApiContext, USERS_COLUMNS, type User, type UserAttachment, type UserContext, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyInternalSignatureInput, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, type YjsContext, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, broadcastChange, broadcastYjsUpdate, buildCronContext, buildInternalPayload, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, cancelSubscription, capToolResultSize, captureScreenshot, checkFieldPermissions, coerceValue, collectionTableName, columnId, computeDoMigration, computeHmacHex, createChat, createDeepSpaceAI, createDeepSpaceAuth, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, deleteRecord, executeQuery, getAllUsers, getChat, getGlobalDOSchemas, getGlobalDOType, getOrCreateYjsDoc, getRecord, getRolePermissions, getSubscription, getUser, getYjsDocKey, handleApiRequest, handleDelete, handlePut, handleSetRole, handleSubscribe, handleToolsRequest, handleUnsubscribe, handleUserList, handleUserUpdate, handleYjsBinaryMessage, handleYjsJoin, handleYjsLeave, isAutoProvision, isOwner, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, putRecord, readRecord, recordMatchesSubscription, refundInvoice, registerUser, requireSubscription, resolveAppName, resolveColumn, rowToData, runMigrations, saveYjsDoc, signInternalPayload, timingSafeEqualHex, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyInternalSignature, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema };
+export { AI_CHATS_SCHEMA, AI_MESSAGES_SCHEMA, ALLOWED_BINDING_TYPES, APP_NAME_RULES, AUTO_PROVISIONABLE_TYPES, AUTO_PROVISION_SENTINEL, type ActionContext, type ActionHandler, type ActionResult, type ActionTools, type ApiWorkerEnv, type AppNameResolution, type AppNameValidation, type AuthWorkerEnv, BASE_USERS_SCHEMA, BUILT_IN_TOOLS, BaseRoom, CHANNELS_SCHEMA, CHANNEL_INVITATIONS_SCHEMA, CHANNEL_MEMBERS_SCHEMA, CONVERSATION_SCHEMAS, COST_RATES, CancelSubscriptionError, type CancelSubscriptionOpts, type CancelSubscriptionResult, CanvasRoom, type CanvasShape, type ChatContextConfig, type ChatMessageRow, type ChatRow, type ChatTurn, type CollectionPermissionSummary, type CollectionSchema, type ColumnDefinition, type ColumnInterpretation, 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, DEFAULT_CONTEXT_CONFIG, DEFAULT_DO_MANIFEST, DEFAULT_MAX_SKEW_MS, DIRECTORY_SCHEMAS, type DOBindings, type DOManifest, type DOManifestEntry, type DebugApiContext, type DeepSpaceAIEnv, type DeepSpaceAIOptions, type DeepSpaceAuth, type DeepSpaceAuthConfig, 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 InternalSignature, type Job, type JobContext, JobRoom, type JobRoomConfig, type JobStatus, type JwtClaims, type JwtVerifierConfig, MESSAGES_SCHEMA, type MutateActionData, type PermissionAnalysis, type PermissionContext, type PermissionLevel, type PermissionSource, type PlanInfo, type PlatformWorkerEnv, type Player, type PrefixResult, type PresencePeer, PresenceRoom, type QueryActionData, REACTIONS_SCHEMA, READ_RECEIPTS_SCHEMA, RESERVED_BINDING_NAMES, RESERVED_COLLECTION_NAMES, type RecordContext, RecordRoom, type RecordRoomConfig, RefundError, type RefundOpts, type RefundResult, type ResolvedColumn, type ResolvedPermission, type RolePermissions, type RunMigrationsResult, SYSTEM_COLLECTION_SCHEMAS, SYSTEM_MANAGED_COLUMNS, SchemaRegistry, type ScopeContext, type ScopedR2Auth, type ScopedR2Config, type ScopedR2Handler, type ScreenshotEnv, type ScreenshotOptions, type ScreenshotResult, type SharedConnection, type SignInternalPayloadInput, type StoredRecord, SubscriptionAuthError, type SubscriptionContext, type SubscriptionRead, SubscriptionRequiredError, type SubscriptionStatus, type Summarizer, type TokenDebugInfo, type ToolResult, type ToolSchema, type ToolsApiContext, USERS_COLUMNS, type User, type UserAttachment, type UserContext, VOTING_SCHEMAS, type ValidationError, type VerifiedAuth, type VerifyInternalSignatureInput, type VerifyOutcome, type VerifyResult, type Viewport, WORKSPACE_SCHEMAS, type YjsContext, YjsRoom, analyzePermissions, apiWorkerFetch, appendMessage, applySlidingWindow, authWorkerFetch, bindingManifestFromOutputConfig, broadcastChange, broadcastYjsUpdate, buildCronContext, buildInternalPayload, buildTableSelect, buildUiParts, canCreate, canDelete, canRead, canUpdate, cancelSubscription, capToolResultSize, captureScreenshot, checkFieldPermissions, coerceValue, collectionTableName, columnId, computeDoMigration, computeHmacHex, createChat, createDeepSpaceAI, createDeepSpaceAuth, createScopedR2Handler, dataToColumnValues, decodeJwtPayload, deleteChatCascade, deleteRecord, enqueueJob, executeQuery, getAllUsers, getChat, getGlobalDOSchemas, getGlobalDOType, getOrCreateYjsDoc, getRecord, getRolePermissions, getSubscription, getUser, getYjsDocKey, handleApiRequest, handleDelete, handlePut, handleSetRole, handleSubscribe, handleToolsRequest, handleUnsubscribe, handleUserList, handleUserUpdate, handleYjsBinaryMessage, handleYjsJoin, handleYjsLeave, isAutoProvision, isOwner, lintSchema, loadMessages, makeDefaultSummarizer, meterAi, meterUsage, meterVectorize, noopPermissionContext, platformWorkerFetch, prepareMessagesWithCompaction, priceBindingUsageEvent, putRecord, readRecord, recordMatchesSubscription, refundInvoice, registerUser, requireSubscription, resolveAppName, resolveColumn, rowToData, runMigrations, saveYjsDoc, signInternalPayload, timingSafeEqualHex, totalChars, truncateOldToolResults, turnsToCoreMessages, unwrapToolOutput, updateChat, validateAppName, validateBindingManifest, validateDoManifest, verifyInternalSignature, verifyJwt, workspaceAccountsSchema, workspaceContentSharesSchema, workspaceEmailHandlesSchema, workspaceFormResponsesSchema, workspacePeopleSchema, workspaceProjectsSchema, workspaceTagsSchema, workspaceTasksSchema, workspaceTeamMembersSchema, workspaceTeamsSchema, workspaceTransactionsSchema };