@agent-native/core 0.134.1 → 0.135.1

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/reset-chunks.post.ts

@@ -24,15 +24,19 @@
  * Route: POST /api/uploads/:recordingId/reset-chunks
  */
 
+import { randomUUID } from "node:crypto";
+
 import {
+  compareAndSetAppState,
+  readAppState,
   writeAppState,
-  deleteAppStateByPrefix,
 } from "@agent-native/core/application-state";
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import { getActiveFileUploadProviderForRequest } from "@agent-native/core/file-upload";
 import { runWithRequestContext } from "@agent-native/core/server";
 import type { UploadMode } from "@shared/recording-core.js";
 import { MAX_UPLOAD_BYTES as MAX_RECORDING_UPLOAD_BYTES } from "@shared/upload-limits.js";
-import { and, eq } from "drizzle-orm";
+import { and, eq, isNull } from "drizzle-orm";
 import {
   defineEventHandler,
   getRouterParam,
@@ -41,8 +45,10 @@ import {
   type H3Event,
 } from "h3";
 
+import { UPLOAD_RETRY_RESUME_FLAG } from "../../../../../shared/feature-flags.js";
 import { getDb, schema } from "../../../../db/index.js";
 import { isMediaVerificationPending } from "../../../../lib/media-verification-state.js";
+import { deleteRecordingChunks } from "../../../../lib/recording-upload-state.js";
 import {
   getEventOwnerContext,
   ownerEmailMatches,
@@ -52,7 +58,10 @@ import {
   setResumableSession,
 } from "../../../../lib/resumable-session.js";
 import { shouldEnableStreamingUpload } from "../../../../lib/streaming-upload-mode.js";
-import { uploadLeaseExpiry } from "../../../../lib/upload-lease.js";
+import {
+  renewUploadLease,
+  uploadLeaseExpiry,
+} from "../../../../lib/upload-lease.js";
 import { allowsSqlRecordingChunkScratch } from "../../../../lib/video-storage.js";
 
 interface CompressionMeta {
@@ -98,7 +107,15 @@ export default defineEventHandler(async (event: H3Event) => {
     compression?: CompressionMeta | null;
     requestStreaming?: boolean;
     mimeType?: string;
+    attemptId?: string;
+    uploadGenerationId?: string;
+    useGenerationFence?: boolean;
   } | null;
+  const recoveryEnabled = await isFeatureFlagEnabled(UPLOAD_RETRY_RESUME_FLAG, {
+    userEmail: ownerEmail,
+    userKey: ownerEmail,
+    orgId,
+  });
 
   // Sanitize compression metadata. The recorder is the only client we trust
   // here, but the values land in Sentry extras — so we still bound them to
@@ -121,6 +138,8 @@ export default defineEventHandler(async (event: H3Event) => {
         id: schema.recordings.id,
         status: schema.recordings.status,
         videoUrl: schema.recordings.videoUrl,
+        uploadAttemptId: schema.recordings.uploadAttemptId,
+        uploadGenerationId: schema.recordings.uploadGenerationId,
       })
       .from(schema.recordings)
       .where(
@@ -140,6 +159,35 @@ export default defineEventHandler(async (event: H3Event) => {
       return { error: "Recording is already ready" };
     }
 
+    const requestedAttemptId =
+      typeof body?.attemptId === "string" &&
+      body.attemptId.length > 0 &&
+      body.attemptId.length <= 128
+        ? body.attemptId
+        : null;
+    const existingAttemptId = existing.uploadAttemptId ?? null;
+    const existingGenerationId = existing.uploadGenerationId ?? null;
+    if (recoveryEnabled && existingAttemptId !== requestedAttemptId) {
+      setResponseStatus(event, 409);
+      return {
+        error: "A newer upload retry is already active.",
+        staleAttempt: true,
+      };
+    }
+    const requestedGenerationId =
+      typeof body?.uploadGenerationId === "string" &&
+      body.uploadGenerationId.length > 0 &&
+      body.uploadGenerationId.length <= 128
+        ? body.uploadGenerationId
+        : null;
+    if (recoveryEnabled && existingGenerationId !== requestedGenerationId) {
+      setResponseStatus(event, 409);
+      return {
+        error: "A newer upload generation is already active.",
+        staleAttempt: true,
+      };
+    }
+
     if (
       await isMediaVerificationPending({
         ownerEmail,
@@ -150,15 +198,72 @@ export default defineEventHandler(async (event: H3Event) => {
       setResponseStatus(event, 409);
       return { error: "Recording is still being verified" };
     }
+    if (existing.status !== "uploading" && existing.status !== "failed") {
+      setResponseStatus(event, 409);
+      return { error: "Recording upload is no longer resettable" };
+    }
 
-    const cleared = await deleteAppStateByPrefix(
-      `recording-chunks-${recordingId}-`,
+    // Fence this reset before deleting any provider or buffered state. A
+    // retry that lost the token race must not tear down the winner's session.
+    const now = new Date().toISOString();
+    // Only clients that can carry the returned generation may opt into the
+    // fence. Retry claims always opt in; legacy reset callers keep the null
+    // generation wire contract until they are upgraded.
+    const useGenerationFence =
+      recoveryEnabled &&
+      (requestedAttemptId !== null ||
+        requestedGenerationId !== null ||
+        body?.useGenerationFence === true);
+    const nextGenerationId = useGenerationFence ? randomUUID() : null;
+    const uploadStateKey = `recording-upload-${recordingId}`;
+    const uploadStateSnapshot = await readAppState(uploadStateKey);
+    const reset = await db
+      .update(schema.recordings)
+      .set({
+        status: "uploading",
+        failureReason: null,
+        uploadProgress: 0,
+        uploadGenerationId: nextGenerationId,
+        ...(!recoveryEnabled ? { uploadAttemptId: null } : {}),
+        uploadLeaseExpiresAt: uploadLeaseExpiry(),
+        updatedAt: now,
+      })
+      .where(
+        and(
+          eq(schema.recordings.id, recordingId),
+          ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+          eq(schema.recordings.status, existing.status),
+          existingAttemptId === null
+            ? isNull(schema.recordings.uploadAttemptId)
+            : eq(schema.recordings.uploadAttemptId, existingAttemptId),
+          existingGenerationId === null
+            ? isNull(schema.recordings.uploadGenerationId)
+            : eq(schema.recordings.uploadGenerationId, existingGenerationId),
+        ),
+      )
+      .returning({ id: schema.recordings.id });
+
+    if (reset.length !== 1) {
+      setResponseStatus(event, 409);
+      return {
+        error: "A newer upload retry is already active.",
+        staleAttempt: true,
+      };
+    }
+
+    const cleared = await deleteRecordingChunks(
+      ownerEmail,
+      recordingId,
+      existingGenerationId,
     );
     // Clear any stale resumable session so a buffered retry does not
     // accidentally route through handleResumableChunk with stale offsets.
-    await deleteResumableSession(recordingId).catch(() => {});
+    await deleteResumableSession(recordingId, existingGenerationId).catch(
+      () => {},
+    );
 
     let uploadMode: UploadMode = "buffered";
+    let compensateStartedSession: (() => Promise<void>) | null = null;
     if (body?.requestStreaming === true) {
       const mimeType = normalizeVideoMimeType(body.mimeType);
       if (!mimeType) {
@@ -184,17 +289,33 @@ export default defineEventHandler(async (event: H3Event) => {
             mimeType,
             MAX_RECORDING_UPLOAD_BYTES,
           );
-          await setResumableSession(recordingId, {
-            providerId: uploadProvider.id,
-            sessionId: session.sessionId,
-            meta: {
-              ...session.meta,
-              stableUrl: true,
-              recordAsset: false,
+          await setResumableSession(
+            recordingId,
+            {
+              providerId: uploadProvider.id,
+              sessionId: session.sessionId,
+              meta: {
+                ...session.meta,
+                stableUrl: true,
+                recordAsset: false,
+              },
+              bytesUploaded: 0,
+              lastCommittedIndex: -1,
             },
-            bytesUploaded: 0,
-            lastCommittedIndex: -1,
-          });
+            nextGenerationId,
+          );
+          compensateStartedSession = async () => {
+            if (!uploadProvider.resumable?.abortSession) {
+              throw new Error(
+                `Resumable upload provider ${uploadProvider.id} cannot abort the discarded retry session`,
+              );
+            }
+            await uploadProvider.resumable.abortSession({
+              sessionId: session.sessionId,
+              meta: session.meta,
+            });
+            await deleteResumableSession(recordingId, nextGenerationId);
+          };
           uploadMode = "streaming";
         } catch (err) {
           if (!bufferedFallbackAvailable) {
@@ -219,19 +340,64 @@ export default defineEventHandler(async (event: H3Event) => {
       }
     }
 
+    const resetLease = await renewUploadLease(recordingId, {
+      attemptId: recoveryEnabled ? existingAttemptId : null,
+      generationId: nextGenerationId,
+    });
+    if (!resetLease.held) {
+      await compensateStartedSession?.();
+      setResponseStatus(event, 409);
+      return {
+        error: "Recording upload changed while its retry was starting.",
+        staleAttempt: true,
+      };
+    }
+
     // Reset the per-recording upload progress so the UI poller sees the
     // re-upload restart from 0 and doesn't briefly show "100% then
     // re-running" on the post-compression chunked upload pass.
-    const now = new Date().toISOString();
-    await writeAppState(`recording-upload-${recordingId}`, {
-      recordingId,
-      status: "uploading",
-      progress: 0,
-      chunksReceived: 0,
-      bytesReceived: 0,
-      maxBytes: MAX_RECORDING_UPLOAD_BYTES,
-      updatedAt: now,
-    });
+    const uploadStateUpdated = await compareAndSetAppState(
+      uploadStateKey,
+      uploadStateSnapshot,
+      {
+        recordingId,
+        status: "uploading",
+        progress: 0,
+        chunksReceived: 0,
+        bytesReceived: 0,
+        uploadAttemptId: recoveryEnabled ? existingAttemptId : null,
+        uploadGenerationId: nextGenerationId,
+        maxBytes: MAX_RECORDING_UPLOAD_BYTES,
+        updatedAt: now,
+      },
+    );
+    if (!uploadStateUpdated) {
+      const [current] = await db
+        .select({
+          status: schema.recordings.status,
+          uploadAttemptId: schema.recordings.uploadAttemptId,
+          uploadGenerationId: schema.recordings.uploadGenerationId,
+        })
+        .from(schema.recordings)
+        .where(
+          and(
+            eq(schema.recordings.id, recordingId),
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+          ),
+        );
+      if (
+        current?.status !== "uploading" ||
+        (current.uploadAttemptId ?? null) !==
+          (recoveryEnabled ? existingAttemptId : null) ||
+        (current.uploadGenerationId ?? null) !== nextGenerationId
+      ) {
+        setResponseStatus(event, 409);
+        return {
+          error: "Recording upload changed while its retry was starting.",
+          staleAttempt: true,
+        };
+      }
+    }
 
     // Stash compression metadata under its own key. We don't merge it into
     // `recording-upload-{id}` because the recorder client overwrites that
@@ -245,25 +411,13 @@ export default defineEventHandler(async (event: H3Event) => {
       });
     }
 
-    await db
-      .update(schema.recordings)
-      .set({
-        status: "uploading",
-        failureReason: null,
-        uploadProgress: 0,
-        // A retry re-takes the lease. Without this the row would go back to
-        // 'uploading' still carrying the expired lease that killed it.
-        uploadLeaseExpiresAt: uploadLeaseExpiry(),
-        updatedAt: now,
-      })
-      .where(eq(schema.recordings.id, recordingId));
-
     return {
       ok: true,
       recordingId,
       chunksCleared: cleared,
       compressionRecorded: !!compression,
       uploadMode,
+      uploadGenerationId: nextGenerationId,
     };
   });
 });

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/resume.get.ts

@@ -11,17 +11,25 @@
  * Route: GET /api/uploads/:recordingId/resume
  */
 
+import {
+  compareAndSetAppState,
+  readAppState,
+  writeAppState,
+} from "@agent-native/core/application-state";
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import { runWithRequestContext } from "@agent-native/core/server";
-import { and, eq } from "drizzle-orm";
+import { and, eq, isNull } from "drizzle-orm";
 import {
   createError,
   defineEventHandler,
   getRouterParam,
+  getQuery,
   setResponseHeader,
   setResponseStatus,
   type H3Event,
 } from "h3";
 
+import { UPLOAD_RETRY_RESUME_FLAG } from "../../../../../shared/feature-flags.js";
 import { getDb, schema } from "../../../../db/index.js";
 import {
   listRecordingChunkKeys,
@@ -33,7 +41,11 @@ import {
   ownerEmailMatches,
 } from "../../../../lib/recordings.js";
 import { getResumableSession } from "../../../../lib/resumable-session.js";
-import { renewUploadLease } from "../../../../lib/upload-lease.js";
+import {
+  isRetryableUploadInterruption,
+  RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+} from "../../../../lib/upload-interruption.js";
+import { uploadLeaseExpiry } from "../../../../lib/upload-lease.js";
 
 export default defineEventHandler(async (event: H3Event) => {
   setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
@@ -41,6 +53,21 @@ export default defineEventHandler(async (event: H3Event) => {
   if (!recordingId) {
     throw createError({ statusCode: 400, message: "Missing recordingId" });
   }
+  const requestedAttemptIdValue = getQuery(event).attemptId;
+  const requestedAttemptId = Array.isArray(requestedAttemptIdValue)
+    ? requestedAttemptIdValue[0]
+    : requestedAttemptIdValue;
+  if (
+    typeof requestedAttemptId !== "string" ||
+    requestedAttemptId.length < 16 ||
+    requestedAttemptId.length > 128 ||
+    !/^[A-Za-z0-9_-]+$/.test(requestedAttemptId)
+  ) {
+    throw createError({
+      statusCode: 400,
+      message: "A valid upload retry attemptId is required",
+    });
+  }
 
   let ownerEmail: string;
   let orgId: string | undefined;
@@ -52,6 +79,21 @@ export default defineEventHandler(async (event: H3Event) => {
     throw createError({ statusCode: 401, message: "Unauthorized" });
   }
 
+  const recoveryEnabled = await isFeatureFlagEnabled(UPLOAD_RETRY_RESUME_FLAG, {
+    userEmail: ownerEmail,
+    userKey: ownerEmail,
+    orgId,
+  });
+  if (!recoveryEnabled) {
+    return {
+      recoveryEnabled: false,
+      resumable: false,
+      recordingId,
+      status: null,
+      reason: "feature_disabled",
+    };
+  }
+
   return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
     const [recording] = await getDb()
       .select({
@@ -59,6 +101,9 @@ export default defineEventHandler(async (event: H3Event) => {
         status: schema.recordings.status,
         failureReason: schema.recordings.failureReason,
         videoUrl: schema.recordings.videoUrl,
+        uploadProgress: schema.recordings.uploadProgress,
+        uploadAttemptId: schema.recordings.uploadAttemptId,
+        uploadGenerationId: schema.recordings.uploadGenerationId,
       })
       .from(schema.recordings)
       .where(
@@ -73,31 +118,160 @@ export default defineEventHandler(async (event: H3Event) => {
       return { error: "Recording not found" };
     }
 
-    const lease = await renewUploadLease(recordingId);
-    if (!lease.held) {
+    // Legacy rows keep their null generation and unscoped scratch. A reset
+    // upgrades them by installing a fresh generation before it deletes data.
+    const existingGenerationId = recording.uploadGenerationId ?? null;
+    const generationId = existingGenerationId;
+    const session = generationId
+      ? await getResumableSession(recordingId, generationId)
+      : await getResumableSession(recordingId);
+    const retryableFailure =
+      recording.status === "failed" &&
+      isRetryableUploadInterruption(recording.failureReason);
+    const existingAttemptId = recording.uploadAttemptId ?? null;
+    if (
+      recording.status === "uploading" &&
+      existingAttemptId !== null &&
+      existingAttemptId !== requestedAttemptId
+    ) {
+      setResponseStatus(event, 409);
+      return {
+        resumable: false,
+        recoveryEnabled: true,
+        recordingId,
+        status: "uploading",
+        reason: "retry_already_active",
+      };
+    }
+    if (recording.status !== "uploading" && !retryableFailure) {
+      return {
+        resumable: false,
+        recoveryEnabled: true,
+        recordingId,
+        status: recording.status,
+        failureReason: recording.failureReason,
+        videoUrl: recording.videoUrl,
+      };
+    }
+
+    const uploadStateKey = `recording-upload-${recordingId}`;
+    const uploadStateRaw = await readAppState(uploadStateKey);
+    const uploadState = uploadStateRaw ?? {};
+    const attemptId = requestedAttemptId;
+    const now = new Date().toISOString();
+    const claimed = await getDb()
+      .update(schema.recordings)
+      .set({
+        status: "uploading",
+        failureReason: null,
+        uploadAttemptId: attemptId,
+        ...(generationId ? { uploadGenerationId: generationId } : {}),
+        uploadLeaseExpiresAt: uploadLeaseExpiry(),
+        updatedAt: now,
+      })
+      .where(
+        and(
+          eq(schema.recordings.id, recordingId),
+          ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+          retryableFailure
+            ? eq(schema.recordings.status, "failed")
+            : eq(schema.recordings.status, "uploading"),
+          retryableFailure
+            ? eq(
+                schema.recordings.failureReason,
+                RETRYABLE_UPLOAD_INTERRUPTION_REASON,
+              )
+            : undefined,
+          existingAttemptId === null
+            ? isNull(schema.recordings.uploadAttemptId)
+            : eq(schema.recordings.uploadAttemptId, existingAttemptId),
+          existingGenerationId === null
+            ? isNull(schema.recordings.uploadGenerationId)
+            : eq(schema.recordings.uploadGenerationId, existingGenerationId),
+        ),
+      )
+      .returning({ id: schema.recordings.id });
+
+    if (claimed.length !== 1) {
+      setResponseStatus(event, 409);
       return {
         resumable: false,
+        recoveryEnabled: true,
         recordingId,
-        status: lease.status,
-        failureReason: lease.failureReason,
-        videoUrl: lease.videoUrl,
+        status: "uploading",
+        reason: "retry_already_active",
       };
     }
 
-    const session = await getResumableSession(recordingId).catch(() => null);
+    const uploadStateUpdated = await compareAndSetAppState(
+      uploadStateKey,
+      uploadStateRaw,
+      {
+        ...uploadState,
+        recordingId,
+        status: "uploading",
+        failureReason: null,
+        retryableInterruption: false,
+        progress: recording.uploadProgress,
+        uploadAttemptId: attemptId,
+        uploadGenerationId: generationId,
+        ...(session ? { bytesReceived: session.bytesUploaded } : {}),
+        updatedAt: now,
+      },
+    );
+    if (!uploadStateUpdated) {
+      const [current] = await getDb()
+        .select({
+          status: schema.recordings.status,
+          uploadAttemptId: schema.recordings.uploadAttemptId,
+          uploadGenerationId: schema.recordings.uploadGenerationId,
+        })
+        .from(schema.recordings)
+        .where(
+          and(
+            eq(schema.recordings.id, recordingId),
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+          ),
+        );
+      if (
+        current?.status !== "uploading" ||
+        (current.uploadAttemptId ?? null) !== attemptId ||
+        (current.uploadGenerationId ?? null) !== generationId
+      ) {
+        setResponseStatus(event, 409);
+        return {
+          resumable: false,
+          recoveryEnabled: true,
+          recordingId,
+          status: current?.status ?? null,
+          reason: "upload_state_changed",
+        };
+      }
+      console.info(
+        `[upload-resume] upload state advanced under the same claim; preserving newer progress for ${recordingId}`,
+      );
+    }
+    await writeAppState("refresh-signal", { ts: Date.now() });
+
     if (session) {
       return {
         resumable: true,
+        recoveryEnabled: true,
         recordingId,
-        status: recording.status,
+        status: "uploading",
         uploadMode: "streaming" as const,
+        attemptId,
+        ...(generationId ? { uploadGenerationId: generationId } : {}),
         bytesReceived: session.bytesUploaded,
         nextChunkIndex: (session.lastCommittedIndex ?? -1) + 1,
       };
     }
 
     const stored = new Set(
-      (await listRecordingChunkKeys(ownerEmail, recordingId))
+      (generationId
+        ? await listRecordingChunkKeys(ownerEmail, recordingId, generationId)
+        : await listRecordingChunkKeys(ownerEmail, recordingId)
+      )
         .map(recordingChunkIndexFromKey)
         .filter((index): index is number => index !== null),
     );
@@ -108,10 +282,15 @@ export default defineEventHandler(async (event: H3Event) => {
 
     return {
       resumable: true,
+      recoveryEnabled: true,
       recordingId,
-      status: recording.status,
+      status: "uploading",
       uploadMode: "buffered" as const,
-      bytesReceived: await sumRecordingChunkBytes(ownerEmail, recordingId),
+      attemptId,
+      ...(generationId ? { uploadGenerationId: generationId } : {}),
+      bytesReceived: generationId
+        ? await sumRecordingChunkBytes(ownerEmail, recordingId, generationId)
+        : await sumRecordingChunkBytes(ownerEmail, recordingId),
       nextChunkIndex,
     };
   });

package/corpus/templates/clips/shared/clips-ai-prefs.ts

@@ -27,10 +27,16 @@ export type ClipsAiPrefs = {
 
 export type ClipsUserPrefs = ClipsAiPrefs & {
   defaultPlaybackSpeed?: string;
+  /** Activity emails (comments, replies, reactions) only — never share invites. */
   emailNotifications?: boolean;
   transcriptCleanupEnabled?: boolean;
+  /** Overrides the organization default visibility for new recordings. */
+  defaultRecordingVisibility?: ClipsDefaultVisibility;
 };
 
+/** Visibility applied to new recordings unless the creator picks another. */
+export type ClipsDefaultVisibility = "private" | "org" | "public";
+
 export function isIncludeFullVideoInAiEnabled(
   prefs: ClipsAiPrefs | Record<string, unknown> | null | undefined,
 ): boolean {

package/corpus/templates/clips/shared/feature-flags.ts

@@ -28,7 +28,19 @@ export const CUSTOM_SCK_LIVE_UPLOAD_FLAG = defineFeatureFlag({
     "Upload recording chunks while capture is still in progress. Requires the custom ScreenCaptureKit pipeline.",
 });
 
+/**
+ * Desktop app and hosted upload routes: preserve interrupted resumable
+ * sessions and continue saved retries from the provider-confirmed offset.
+ */
+export const UPLOAD_RETRY_RESUME_FLAG = defineFeatureFlag({
+  key: "uploadRetryResume",
+  displayName: "Resumable upload retry",
+  description:
+    "Resume interrupted desktop uploads from their last confirmed byte instead of replaying the full local backup.",
+});
+
 export const CLIPS_FEATURE_FLAGS = defineFeatureFlags([
   USE_CUSTOM_SCK_PIPELINE_FLAG,
   CUSTOM_SCK_LIVE_UPLOAD_FLAG,
+  UPLOAD_RETRY_RESUME_FLAG,
 ]);

package/corpus/templates/clips/shared/recording-core.ts

@@ -76,6 +76,7 @@ export type ChunkUploadParams = {
   height?: number | null;
   hasAudio?: boolean;
   hasCamera?: boolean;
+  uploadGenerationId?: string;
 };
 
 export function normalizeChunkUploadNumber(value: unknown): number | undefined {
@@ -115,6 +116,9 @@ export function chunkUploadQuery(params: ChunkUploadParams): string {
   if (params.hasCamera !== undefined) {
     q.set("hasCamera", params.hasCamera ? "1" : "0");
   }
+  if (params.uploadGenerationId) {
+    q.set("uploadGenerationId", params.uploadGenerationId);
+  }
   return q.toString();
 }