deepspace 0.20.0 → 0.21.0

package/dist/{public-CFAj1hL2.d.ts → public-DenQ1TsZ.d.ts}

@@ -1,4 +1,24 @@
 import { ReactNode, ReactElement, ComponentType } from 'react';
+import { z } from 'zod';
+
+declare const themeObjectSchema: z.ZodObject<{
+    accent: z.ZodOptional<z.ZodString>;
+    accentDark: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodString>;
+    density: z.ZodOptional<z.ZodEnum<{
+        comfortable: "comfortable";
+        compact: "compact";
+    }>>;
+    logo: z.ZodOptional<z.ZodString>;
+    logoDark: z.ZodOptional<z.ZodString>;
+    favicon: z.ZodOptional<z.ZodString>;
+    defaultMode: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        system: "system";
+    }>>;
+    strictMode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
 
 type DocumentationAssistantAccess = 'disabled' | 'public' | 'authenticated';
 type DocumentationMcpAccess = 'disabled' | 'public';
@@ -10,11 +30,21 @@ interface DocumentationFontConfig {
     source?: string;
     format?: string;
 }
-interface DocumentationThemeConfig {
-    preset?: string;
-    accent?: string;
-    accentDark?: string;
-    background?: string;
+/**
+ * The `theme` object as authored in documentation.json — exactly the keys
+ * the config schema accepts under `theme.*`, derived from that schema so
+ * the two can never drift. Everything else (fonts, background decoration,
+ * styling, logo href) is configured through the Mintlify-style top-level
+ * keys and only exists on the resolved theme.
+ */
+type DocumentationThemeConfig = z.infer<typeof themeObjectSchema>;
+/**
+ * The fully resolved theme after config loading merges `theme.*` with the
+ * Mintlify top-level keys (`colors`, `logo`, `favicon`, `appearance`,
+ * `background`, `fonts`, `styling`). This is what the template and runtime
+ * consume; it is an output shape, never accepted as `theme.*` input.
+ */
+interface ResolvedDocumentationTheme extends DocumentationThemeConfig {
     backgroundDark?: string;
     backgroundDecoration?: 'none' | 'gradient' | 'grid';
     bodyFont?: DocumentationFontConfig;
@@ -22,12 +52,7 @@ interface DocumentationThemeConfig {
     monoFont?: DocumentationFontConfig;
     codeBlockMode?: 'dark' | 'system';
     eyebrowStyle?: 'section' | 'breadcrumbs' | 'none';
-    logo?: string;
-    logoDark?: string;
     logoHref?: string;
-    favicon?: string;
-    defaultMode?: 'light' | 'dark' | 'system';
-    strictMode?: boolean;
 }
 interface DocumentationLinkConfig {
     label: string;
@@ -79,7 +104,7 @@ interface DocumentationConfig {
     url?: string;
     /** Explicit custom hostnames that mount this documentation at `/`. */
     domains: string[];
-    theme: DocumentationThemeConfig;
+    theme: ResolvedDocumentationTheme;
     navigation?: DocumentationNavigationItem[];
     links: DocumentationLinkConfig[];
     footer: DocumentationLinkConfig[];

package/dist/server.d.ts

@@ -1532,6 +1532,7 @@ declare const MSG: {
     readonly CRON_PAUSE: "cron.pause";
     readonly CRON_RESUME: "cron.resume";
     readonly CRON_STATUS: "cron.status";
+    readonly CRON_ACK: "cron.ack";
     readonly JOB_ENQUEUE: "job.enqueue";
     readonly JOB_CANCEL: "job.cancel";
     readonly JOB_RETRY: "job.retry";
@@ -1699,6 +1700,16 @@ type ServerMessage = BaseMessage<typeof MSG.QUERY_RESULT, {
 }> | BaseMessage<typeof MSG.CRON_STATUS, {
     tasks: unknown;
     recentHistory: unknown;
+}> | BaseMessage<typeof MSG.CRON_ACK, {
+    requestId: string;
+    taskName: string;
+    ok: true;
+} | {
+    requestId: string;
+    taskName?: string;
+    ok: false;
+    reason: 'read_only' | 'unknown_task' | 'failed';
+    error?: string;
 }> | BaseMessage<typeof MSG.JOB_UPDATE, {
     kind: 'snapshot' | 'enqueued' | 'progress' | 'succeeded' | 'failed' | 'canceled' | 'retried';
     job?: unknown;
@@ -2313,12 +2324,22 @@ declare abstract class CronRoom<E = Record<string, unknown>> extends BaseRoom<E>
         type: string;
         [key: string]: unknown;
     }): Promise<void>;
+    private dispatchMessage;
     protected onAlarm(): Promise<void>;
     private executeTask;
     private scheduleNextAlarm;
     private getTaskStates;
     private getRecentHistory;
     private broadcastStatus;
+    /**
+     * Receipt for a mutation frame, addressed only to its sender. Receipts
+     * are opt-in by correlation id: frames without a `requestId` keep the
+     * fire-and-forget contract, so the (untyped) `requestId` from the wire
+     * is the single gate here rather than a check at every call site.
+     * Frames go through the shared `serverBuild` constructors so the wire
+     * shape is enforced by the protocol types, not re-spelled here.
+     */
+    private ackMutation;
     /**
      * Execute a scheduled task by name.
      * Called both by the alarm scheduler and manual trigger.

package/dist/server.js

@@ -740,6 +740,9 @@ function declaredLength(request, what) {
 function isKeyWithinScope(key, prefix, excludedPrefixes) {
   return key.startsWith(prefix) && !excludedPrefixes.some((excluded) => key.startsWith(excluded));
 }
+function scopeRelativeKey(key, prefix) {
+  return key.slice(prefix.length);
+}
 function anchorKey(raw, prefix, excludedPrefixes) {
   const safe = sanitizeSubpath(raw);
   if (safe === null) return fail2(400, "Invalid key: traversal not allowed", "invalid_key");
@@ -939,7 +942,7 @@ async function handleUpload(request, url, bucket, prefix, excludedPrefixes, auth
       admission.markerKey,
       admission.markerKey !== null || fileData.byteLength < replacedBytes
     );
-    return storedFileJson(located.key, fileName, url, scope);
+    return storedFileJson(located.key, prefix, fileName, url, scope);
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Upload failed";
     console.error("[handleUpload] Error:", msg, err instanceof Error ? err.stack : "");
@@ -961,11 +964,17 @@ function fileMetadata(fileName, userId, reservationId, declaredBytes) {
     uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-function storedFileJson(key, name, url, scope) {
+function storedFileJson(key, prefix, name, url, scope) {
   const fileUrl = new URL(`/api/files/${encodeKeyPath(key)}`, url.origin);
   fileUrl.searchParams.set("scope", scope);
   return Response.json(
-    { success: true, key, url: fileUrl.toString(), name },
+    {
+      success: true,
+      key,
+      relativeKey: scopeRelativeKey(key, prefix),
+      url: fileUrl.toString(),
+      name
+    },
     { headers: CORS_HEADERS2 }
   );
 }
@@ -1245,7 +1254,7 @@ async function completedReservationObject(bucket, session) {
   const object = await bucket.head(session.key);
   return object?.customMetadata?.reservationId === session.reservationId ? object : null;
 }
-async function finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope) {
+async function finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope, prefix) {
   const declaredMetadata = Number(object.customMetadata?.declaredBytes);
   const declaredBytes = reservation?.declaredBytes ?? (Number.isSafeInteger(declaredMetadata) && declaredMetadata >= 0 ? declaredMetadata : MAX_APP_FILE_BYTES);
   const refusal = overCeiling(object.size) ?? (object.size > declaredBytes ? fail2(
@@ -1279,7 +1288,7 @@ async function finishCompletedMultipart(bucket, session, reservation, object, au
     }
   }
   const name = object.customMetadata?.originalName ?? session.uploadKey.split("/").pop() ?? "file";
-  return storedFileJson(session.key, name, url, scope);
+  return storedFileJson(session.key, prefix, name, url, scope);
 }
 async function multipartComplete(request, url, bucket, prefix, excludedPrefixes, auth, scope) {
   const body = await readControlJson(request);
@@ -1300,7 +1309,7 @@ async function multipartComplete(request, url, bucket, prefix, excludedPrefixes,
   if (auth.storage && !reservation) {
     const completed = await completedReservationObject(bucket, session);
     if (completed) {
-      return finishCompletedMultipart(bucket, session, null, completed, auth, url, scope);
+      return finishCompletedMultipart(bucket, session, null, completed, auth, url, scope, prefix);
     }
     await abandonMultipart(bucket, session, auth, null);
     return quotaUnavailable("This upload reservation is missing or does not match.");
@@ -1339,14 +1348,23 @@ async function multipartComplete(request, url, bucket, prefix, excludedPrefixes,
   } catch (error) {
     const completed = await completedReservationObject(bucket, session);
     if (completed) {
-      return finishCompletedMultipart(bucket, session, reservation, completed, auth, url, scope);
+      return finishCompletedMultipart(
+        bucket,
+        session,
+        reservation,
+        completed,
+        auth,
+        url,
+        scope,
+        prefix
+      );
     }
     if (r2ErrorCode(error) === 10024 && reservation) {
       await releaseQuotaMarker(bucket, auth.storage, reservation.key, true);
     }
     return multipartFailure(error);
   }
-  return finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope);
+  return finishCompletedMultipart(bucket, session, reservation, object, auth, url, scope, prefix);
 }
 async function multipartAbort(url, bucket, prefix, excludedPrefixes, auth) {
   const session = resolveSession(url, prefix, excludedPrefixes);
@@ -1366,37 +1384,49 @@ async function handleList(bucket, prefix, excludedPrefixes, url, scope, auth) {
   const listPrefix = `${prefix}${userPrefix}`;
   const requestedLimit = Number(url.searchParams.get("limit") ?? 100);
   const limit = Number.isSafeInteger(requestedLimit) ? Math.min(1e3, Math.max(1, requestedLimit)) : 100;
+  const requestCursor = url.searchParams.get("cursor");
   if (excludedPrefixes.some((excluded) => listPrefix.startsWith(excluded))) {
     return Response.json({ files: [], truncated: false }, { headers: CORS_HEADERS2 });
   }
-  const listed = await bucket.list({ prefix: listPrefix, limit });
+  const withMetadata = (options) => ({ ...options, include: ["customMetadata"] });
+  const listed = await bucket.list(
+    withMetadata({
+      prefix: listPrefix,
+      limit,
+      ...requestCursor ? { cursor: requestCursor } : {}
+    })
+  );
   const visible = listed.objects.filter(
     (object) => isKeyWithinScope(object.key, prefix, excludedPrefixes)
   );
   const seen = new Set(visible.map((object) => object.key));
-  let truncated = listed.truncated;
-  for (const excluded of excludedPrefixes.filter((candidate) => candidate.startsWith(listPrefix))) {
-    if (visible.length >= limit) break;
+  let frontier = listed;
+  let frontierKey = listed.objects.at(-1)?.key;
+  for (const excluded of excludedPrefixes.filter((candidate) => candidate.startsWith(listPrefix)).sort()) {
+    if (!frontier.truncated || visible.length >= limit) break;
     const excludedEnd = `${excluded}\u{10FFFF}`;
-    const lastListedKey = listed.objects.at(-1)?.key;
-    const after = await bucket.list({
-      prefix: listPrefix,
-      startAfter: lastListedKey && lastListedKey > excludedEnd ? lastListedKey : excludedEnd,
-      limit: limit - visible.length
-    });
+    const after = await bucket.list(
+      withMetadata({
+        prefix: listPrefix,
+        startAfter: frontierKey && frontierKey > excludedEnd ? frontierKey : excludedEnd,
+        limit: limit - visible.length
+      })
+    );
     for (const object of after.objects) {
       if (!seen.has(object.key) && isKeyWithinScope(object.key, prefix, excludedPrefixes)) {
         seen.add(object.key);
         visible.push(object);
       }
     }
-    truncated = after.truncated;
+    frontierKey = after.objects.at(-1)?.key ?? frontierKey;
+    frontier = after;
   }
   const files = visible.slice(0, limit).map((obj) => {
     const fileUrl = new URL(`/api/files/${encodeKeyPath(obj.key)}`, url.origin);
     fileUrl.searchParams.set("scope", scope);
     return {
       key: obj.key,
+      relativeKey: scopeRelativeKey(obj.key, prefix),
       size: obj.size,
       uploaded: obj.uploaded.toISOString(),
       url: fileUrl.toString(),
@@ -1411,7 +1441,12 @@ async function handleList(bucket, prefix, excludedPrefixes, url, scope, auth) {
     if (storage && limitBytes !== null) storage.limitBytes = limitBytes;
   }
   return Response.json(
-    { files, truncated, ...storage ? { storage } : {} },
+    {
+      files,
+      truncated: frontier.truncated,
+      ...frontier.truncated ? { cursor: frontier.cursor } : {},
+      ...storage ? { storage } : {}
+    },
     { headers: CORS_HEADERS2 }
   );
 }
@@ -2952,6 +2987,9 @@ var MSG = {
   CRON_PAUSE: "cron.pause",
   CRON_RESUME: "cron.resume",
   CRON_STATUS: "cron.status",
+  // Per-mutation receipt, sent only to the socket whose trigger/pause/
+  // resume carried a `requestId` — frames without one stay fire-and-forget.
+  CRON_ACK: "cron.ack",
   // ---- JobRoom ---------------------------------------------------------
   // Background-job queue with durable, alarm-driven execution. See
   // server/rooms/job-room.ts. Clients enqueue and subscribe to updates;
@@ -3453,6 +3491,14 @@ var serverBuild = {
   cronTasks: (tasks) => ({ type: MSG.CRON_TASKS, payload: { tasks } }),
   cronHistory: (history) => ({ type: MSG.CRON_HISTORY, payload: { history } }),
   cronStatus: (tasks, recentHistory) => ({ type: MSG.CRON_STATUS, payload: { tasks, recentHistory } }),
+  cronAckSuccess: (requestId, taskName) => ({
+    type: MSG.CRON_ACK,
+    payload: { requestId, taskName, ok: true }
+  }),
+  cronAckFailure: (requestId, reason, error, taskName) => ({
+    type: MSG.CRON_ACK,
+    payload: { requestId, taskName, ok: false, reason, error }
+  }),
   // Jobs
   jobSnapshot: (jobs) => ({ type: MSG.JOB_UPDATE, payload: { kind: "snapshot", jobs } }),
   jobEnqueued: (job, requestId) => ({
@@ -6196,40 +6242,88 @@ var CronRoom = class extends BaseRoom {
   }
   async onMessage(ws, user, message) {
     this.ensureInitialized();
-    const { type, payload } = message;
+    const { type, payload = {} } = message;
     if (CRON_WRITE_TYPES.has(type) && !user.canWrite) {
-      this.sendTo(ws, {
-        type: MSG.ERROR,
-        payload: { error: "Write access denied: viewer role cannot modify cron tasks" }
+      const error = "Write access denied: viewer role cannot modify cron tasks";
+      this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+      this.ackMutation(ws, payload.requestId, {
+        ok: false,
+        taskName: payload.taskName,
+        reason: "read_only",
+        error
       });
       return;
     }
+    try {
+      await this.dispatchMessage(ws, type, payload);
+    } catch (error) {
+      try {
+        this.ackMutation(ws, payload.requestId, {
+          ok: false,
+          taskName: payload.taskName,
+          reason: "failed",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      } catch {
+      }
+      throw error;
+    }
+  }
+  async dispatchMessage(ws, type, payload) {
     switch (type) {
       case MSG.CRON_TRIGGER: {
         const taskName = payload.taskName;
         if (!taskName) {
-          this.sendTo(ws, { type: MSG.ERROR, payload: { error: "Missing taskName" } });
+          const error = "Missing taskName";
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, { ok: false, reason: "failed", error });
           return;
         }
-        if (!await this.executeTask(taskName)) {
-          this.sendTo(ws, {
-            type: MSG.ERROR,
-            payload: { error: `Unknown cron task: ${taskName}` }
+        const execution = await this.executeTask(taskName);
+        if (!execution) {
+          const error = `Unknown cron task: ${taskName}`;
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, {
+            ok: false,
+            taskName,
+            reason: "unknown_task",
+            error
           });
+          break;
         }
+        this.ackMutation(
+          ws,
+          payload.requestId,
+          execution.success ? { ok: true, taskName } : { ok: false, taskName, reason: "failed", error: execution.error }
+        );
         break;
       }
-      case MSG.CRON_PAUSE: {
-        const taskName = payload.taskName;
-        this.sql.exec(`UPDATE cron_tasks SET paused = 1 WHERE name = ?`, taskName);
-        this.broadcastStatus();
-        break;
-      }
+      case MSG.CRON_PAUSE:
       case MSG.CRON_RESUME: {
         const taskName = payload.taskName;
-        this.sql.exec(`UPDATE cron_tasks SET paused = 0 WHERE name = ?`, taskName);
-        this.scheduleNextAlarm();
+        if (!taskName) {
+          const error = "Missing taskName";
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, { ok: false, reason: "failed", error });
+          return;
+        }
+        const known = this.sql.exec(`SELECT name FROM cron_tasks WHERE name = ?`, taskName).toArray().length > 0;
+        if (!known) {
+          const error = `Unknown cron task: ${taskName}`;
+          this.sendTo(ws, { type: MSG.ERROR, payload: { error } });
+          this.ackMutation(ws, payload.requestId, {
+            ok: false,
+            taskName,
+            reason: "unknown_task",
+            error
+          });
+          break;
+        }
+        const paused = type === MSG.CRON_PAUSE;
+        this.sql.exec(`UPDATE cron_tasks SET paused = ? WHERE name = ?`, paused ? 1 : 0, taskName);
+        if (!paused) this.scheduleNextAlarm();
         this.broadcastStatus();
+        this.ackMutation(ws, payload.requestId, { ok: true, taskName });
         break;
       }
       case MSG.CRON_TASKS: {
@@ -6272,7 +6366,7 @@ var CronRoom = class extends BaseRoom {
   // ==========================================================================
   async executeTask(taskName) {
     const taskRow = this.sql.exec(`SELECT interval_minutes, schedule, timezone FROM cron_tasks WHERE name = ?`, taskName).toArray()[0];
-    if (!taskRow) return false;
+    if (!taskRow) return null;
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const start = Date.now();
     let success = true;
@@ -6308,7 +6402,7 @@ var CronRoom = class extends BaseRoom {
       `DELETE FROM cron_history WHERE id NOT IN (SELECT id FROM cron_history ORDER BY id DESC LIMIT 500)`
     );
     this.broadcastStatus();
-    return true;
+    return { taskName, startedAt, completedAt, success, durationMs, error };
   }
   // ==========================================================================
   // Scheduling
@@ -6378,6 +6472,21 @@ var CronRoom = class extends BaseRoom {
       }
     });
   }
+  /**
+   * Receipt for a mutation frame, addressed only to its sender. Receipts
+   * are opt-in by correlation id: frames without a `requestId` keep the
+   * fire-and-forget contract, so the (untyped) `requestId` from the wire
+   * is the single gate here rather than a check at every call site.
+   * Frames go through the shared `serverBuild` constructors so the wire
+   * shape is enforced by the protocol types, not re-spelled here.
+   */
+  ackMutation(ws, requestId, result) {
+    if (typeof requestId !== "string") return;
+    this.sendTo(
+      ws,
+      result.ok ? serverBuild.cronAckSuccess(requestId, result.taskName) : serverBuild.cronAckFailure(requestId, result.reason, result.error, result.taskName)
+    );
+  }
 };
 function computeNextRunAt(task, from) {
   if (task.interval_minutes) {