@agent-native/core 0.173.1 → 0.173.2-nightly-20260825163448

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

@@ -11,6 +11,8 @@
  * Route: GET /api/uploads/:recordingId/resume
  */
 
+import { randomUUID } from "node:crypto";
+
 import {
   compareAndSetAppState,
   readAppState,
@@ -18,7 +20,7 @@ import {
 } from "@agent-native/core/application-state";
 import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import { runWithRequestContext } from "@agent-native/core/server";
-import { and, eq, isNull } from "drizzle-orm";
+import { and, eq, isNull, lte } from "drizzle-orm";
 import {
   createError,
   defineEventHandler,
@@ -40,12 +42,32 @@ import {
   getEventOwnerContext,
   ownerEmailMatches,
 } from "../../../../lib/recordings.js";
-import { getResumableSession } from "../../../../lib/resumable-session.js";
 import {
-  isRetryableUploadInterruption,
-  RETRYABLE_UPLOAD_INTERRUPTION_REASON,
-} from "../../../../lib/upload-interruption.js";
-import { uploadLeaseExpiry } from "../../../../lib/upload-lease.js";
+  deleteResumableSession,
+  getResumableSession,
+} from "../../../../lib/resumable-session.js";
+import { abortResumableUploadSession } from "../../../../lib/resumable-upload-cleanup.js";
+import { isRetryableUploadInterruption } from "../../../../lib/upload-interruption.js";
+import {
+  UPLOAD_LEASE_MS,
+  uploadLeaseExpiry,
+} from "../../../../lib/upload-lease.js";
+
+const RETRY_CLAIM_LIVENESS_MS = 30 * 1000;
+const RETRY_CLAIM_RETRY_AFTER_MIN_MS = 250;
+
+function retryClaimRetryAfterMs(
+  lastHeartbeatMs: number,
+  nowMs: number,
+): number {
+  return Math.max(
+    RETRY_CLAIM_RETRY_AFTER_MIN_MS,
+    Math.min(
+      RETRY_CLAIM_LIVENESS_MS,
+      lastHeartbeatMs + RETRY_CLAIM_LIVENESS_MS - nowMs,
+    ),
+  );
+}
 
 export default defineEventHandler(async (event: H3Event) => {
   setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
@@ -85,13 +107,51 @@ export default defineEventHandler(async (event: H3Event) => {
     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({
+          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 (!recording) {
+        setResponseStatus(event, 404);
+        return { error: "Recording not found" };
+      }
+      if (
+        recording.uploadAttemptId &&
+        recording.uploadAttemptId !== requestedAttemptId
+      ) {
+        setResponseStatus(event, 409);
+        return {
+          recoveryEnabled: false,
+          resumable: false,
+          recordingId,
+          status: recording.status,
+          reason: "retry_already_active",
+        };
+      }
+      return {
+        recoveryEnabled: false,
+        resumable: false,
+        recordingId,
+        status: recording.status ?? null,
+        reason: "feature_disabled",
+        ...(recording.uploadAttemptId
+          ? { attemptId: recording.uploadAttemptId }
+          : {}),
+        ...(recording.uploadGenerationId
+          ? { uploadGenerationId: recording.uploadGenerationId }
+          : {}),
+      };
+    });
   }
 
   return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
@@ -104,6 +164,7 @@ export default defineEventHandler(async (event: H3Event) => {
         uploadProgress: schema.recordings.uploadProgress,
         uploadAttemptId: schema.recordings.uploadAttemptId,
         uploadGenerationId: schema.recordings.uploadGenerationId,
+        uploadLeaseExpiresAt: schema.recordings.uploadLeaseExpiresAt,
       })
       .from(schema.recordings)
       .where(
@@ -121,19 +182,38 @@ export default defineEventHandler(async (event: H3Event) => {
     // 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
+    let generationId = existingGenerationId;
+    let session = generationId
       ? await getResumableSession(recordingId, generationId)
       : await getResumableSession(recordingId);
     const retryableFailure =
       recording.status === "failed" &&
       isRetryableUploadInterruption(recording.failureReason);
     const existingAttemptId = recording.uploadAttemptId ?? null;
-    if (
+    const nowMs = Date.now();
+    const now = new Date(nowMs).toISOString();
+    const staleLeaseThreshold = new Date(
+      nowMs + UPLOAD_LEASE_MS - RETRY_CLAIM_LIVENESS_MS,
+    ).toISOString();
+    const claimLeaseExpiryMs = Date.parse(recording.uploadLeaseExpiresAt ?? "");
+    const claimHeartbeatMs = claimLeaseExpiryMs - UPLOAD_LEASE_MS;
+    const differentRetryClaim =
       recording.status === "uploading" &&
       existingAttemptId !== null &&
-      existingAttemptId !== requestedAttemptId
-    ) {
+      existingAttemptId !== requestedAttemptId;
+    if (differentRetryClaim && !Number.isFinite(claimHeartbeatMs)) {
+      setResponseStatus(event, 409);
+      return {
+        resumable: false,
+        recoveryEnabled: true,
+        recordingId,
+        status: "uploading",
+        reason: "retry_claim_liveness_unavailable",
+      };
+    }
+    const differentLiveRetryClaim =
+      differentRetryClaim && claimHeartbeatMs > nowMs - RETRY_CLAIM_LIVENESS_MS;
+    if (differentLiveRetryClaim) {
       setResponseStatus(event, 409);
       return {
         resumable: false,
@@ -141,6 +221,7 @@ export default defineEventHandler(async (event: H3Event) => {
         recordingId,
         status: "uploading",
         reason: "retry_already_active",
+        retryAfterMs: retryClaimRetryAfterMs(claimHeartbeatMs, nowMs),
       };
     }
     if (recording.status !== "uploading" && !retryableFailure) {
@@ -158,15 +239,21 @@ export default defineEventHandler(async (event: H3Event) => {
     const uploadStateRaw = await readAppState(uploadStateKey);
     const uploadState = uploadStateRaw ?? {};
     const attemptId = requestedAttemptId;
-    const now = new Date().toISOString();
+    const takingOverStaleRetryClaim = differentRetryClaim;
+    const claimedGenerationId = takingOverStaleRetryClaim
+      ? randomUUID()
+      : generationId;
+    const claimedLeaseExpiry = uploadLeaseExpiry(nowMs);
     const claimed = await getDb()
       .update(schema.recordings)
       .set({
         status: "uploading",
         failureReason: null,
         uploadAttemptId: attemptId,
-        ...(generationId ? { uploadGenerationId: generationId } : {}),
-        uploadLeaseExpiresAt: uploadLeaseExpiry(),
+        ...(claimedGenerationId
+          ? { uploadGenerationId: claimedGenerationId }
+          : {}),
+        uploadLeaseExpiresAt: claimedLeaseExpiry,
         updatedAt: now,
       })
       .where(
@@ -177,10 +264,7 @@ export default defineEventHandler(async (event: H3Event) => {
             ? eq(schema.recordings.status, "failed")
             : eq(schema.recordings.status, "uploading"),
           retryableFailure
-            ? eq(
-                schema.recordings.failureReason,
-                RETRYABLE_UPLOAD_INTERRUPTION_REASON,
-              )
+            ? eq(schema.recordings.failureReason, recording.failureReason!)
             : undefined,
           existingAttemptId === null
             ? isNull(schema.recordings.uploadAttemptId)
@@ -188,6 +272,9 @@ export default defineEventHandler(async (event: H3Event) => {
           existingGenerationId === null
             ? isNull(schema.recordings.uploadGenerationId)
             : eq(schema.recordings.uploadGenerationId, existingGenerationId),
+          takingOverStaleRetryClaim
+            ? lte(schema.recordings.uploadLeaseExpiresAt, staleLeaseThreshold)
+            : undefined,
         ),
       )
       .returning({ id: schema.recordings.id });
@@ -200,9 +287,29 @@ export default defineEventHandler(async (event: H3Event) => {
         recordingId,
         status: "uploading",
         reason: "retry_already_active",
+        retryAfterMs: 250,
       };
     }
 
+    if (takingOverStaleRetryClaim && session) {
+      const invalidated = await abortResumableUploadSession(session, {
+        label: `upload-resume-takeover-${recordingId}`,
+      });
+      if (!invalidated) {
+        setResponseStatus(event, 409);
+        return {
+          resumable: false,
+          recoveryEnabled: true,
+          recordingId,
+          status: "uploading",
+          reason: "stale_provider_session_invalidation_failed",
+        };
+      }
+      await deleteResumableSession(recordingId, generationId);
+      session = null;
+    }
+    generationId = claimedGenerationId;
+
     const uploadStateUpdated = await compareAndSetAppState(
       uploadStateKey,
       uploadStateRaw,

package/corpus/templates/content/actions/_database-property-input.ts

@@ -0,0 +1,211 @@
+import { ActionContractError } from "@agent-native/core";
+import { z } from "zod";
+
+const nullable = <T extends z.ZodTypeAny>(schema: T) =>
+  z.union([schema, z.null()]);
+
+const propertyIdSchema = z
+  .string()
+  .min(1)
+  .describe("Exact immutable property definition ID");
+
+const stringPropertyEntry = (
+  propertyType: "text" | "place" | "phone" | "url" | "email",
+  valueDescription: string,
+) =>
+  z
+    .object({
+      propertyId: propertyIdSchema,
+      propertyType: z.literal(propertyType),
+      value: nullable(z.string()).describe(valueDescription),
+    })
+    .strict();
+
+const optionPropertyEntry = (propertyType: "select" | "status") =>
+  z
+    .object({
+      propertyId: propertyIdSchema,
+      propertyType: z.literal(propertyType),
+      value: nullable(z.string()).describe(
+        "Exact option ID or exact option label from the discovered property contract; null explicitly clears the value",
+      ),
+    })
+    .strict();
+
+export const databasePropertyEntrySchema = z.discriminatedUnion(
+  "propertyType",
+  [
+    stringPropertyEntry("text", "Text value; null explicitly clears the value"),
+    stringPropertyEntry(
+      "place",
+      "Place text; null explicitly clears the value",
+    ),
+    stringPropertyEntry(
+      "phone",
+      "Phone text; null explicitly clears the value",
+    ),
+    stringPropertyEntry(
+      "url",
+      "Absolute http/https URL; null explicitly clears the value",
+    ),
+    stringPropertyEntry(
+      "email",
+      "Email address; null explicitly clears the value",
+    ),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("number"),
+        value: nullable(z.number().finite()).describe(
+          "Finite number; use a JSON number rather than numeric text, or null to explicitly clear",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("checkbox"),
+        value: nullable(z.boolean()).describe(
+          "Boolean; use true or false rather than text, or null to explicitly clear",
+        ),
+      })
+      .strict(),
+    optionPropertyEntry("select"),
+    optionPropertyEntry("status"),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("multi_select"),
+        value: nullable(z.array(z.string())).describe(
+          "Option IDs or exact option labels from the discovered property contract; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("date"),
+        value: nullable(
+          z.union([
+            z.string(),
+            z
+              .object({
+                start: z.string(),
+                end: z.string().optional(),
+                includeTime: z.boolean().optional(),
+              })
+              .strict(),
+          ]),
+        ).describe(
+          "ISO date/date-time string or { start, end?, includeTime? }; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("person"),
+        value: nullable(z.array(z.string())).describe(
+          "Person identifiers from the discovered property contract; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+    z
+      .object({
+        propertyId: propertyIdSchema,
+        propertyType: z.literal("files_media"),
+        value: nullable(z.array(z.string())).describe(
+          "Absolute http/https file URLs; null explicitly clears the value",
+        ),
+      })
+      .strict(),
+  ],
+);
+
+export type DatabasePropertyEntry = z.infer<typeof databasePropertyEntrySchema>;
+
+export const databasePropertyValuesSchema = z
+  .record(z.string(), z.unknown())
+  .optional()
+  .describe(
+    "Programmatic property values keyed by exact property definition ID.",
+  );
+
+export const databasePropertyEntriesSchema = z
+  .array(databasePropertyEntrySchema)
+  .min(1)
+  .max(1_000)
+  .optional()
+  .describe(
+    "Typed property values as explicit entries. Copy each propertyType from the discovered mutation contract and include one entry for every writable property value the user requested, using the exact immutable property definition ID. When at least one value was requested, never pass an empty array. Do not invent or clear unmentioned properties.",
+  );
+
+export function normalizeDatabasePropertyInput(input: {
+  propertyEntries?: DatabasePropertyEntry[];
+  propertyValues?: Record<string, unknown>;
+}): {
+  propertyValues: Record<string, unknown> | undefined;
+  propertyTypeAssertions: Record<string, string> | undefined;
+} {
+  if (input.propertyEntries && input.propertyValues) {
+    throw new ActionContractError(
+      "Provide propertyEntries or propertyValues, not both.",
+      { errorCode: "AMBIGUOUS_PROPERTY_INPUT" },
+    );
+  }
+  if (!input.propertyEntries) {
+    return {
+      propertyValues: input.propertyValues,
+      propertyTypeAssertions: undefined,
+    };
+  }
+
+  const values: Record<string, unknown> = Object.create(null) as Record<
+    string,
+    unknown
+  >;
+  const propertyTypes: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  for (const entry of input.propertyEntries) {
+    if (Object.prototype.hasOwnProperty.call(values, entry.propertyId)) {
+      throw new ActionContractError(
+        `Property entry ${entry.propertyId} was provided more than once.`,
+        {
+          errorCode: "DUPLICATE_PROPERTY_INPUT",
+          details: { propertyId: entry.propertyId },
+        },
+      );
+    }
+    values[entry.propertyId] = entry.value;
+    propertyTypes[entry.propertyId] = entry.propertyType;
+  }
+  return {
+    propertyValues: values,
+    propertyTypeAssertions: propertyTypes,
+  };
+}
+
+export function canonicalizeDatabasePropertyInput<
+  T extends {
+    propertyEntries?: DatabasePropertyEntry[];
+    propertyValues?: Record<string, unknown>;
+  },
+>(
+  input: T,
+): Omit<T, "propertyEntries" | "propertyValues"> & {
+  propertyValues?: Record<string, unknown>;
+  propertyTypeAssertions?: Record<string, string>;
+} {
+  const { propertyEntries, propertyValues, ...canonicalInput } = input;
+  const normalized = normalizeDatabasePropertyInput({
+    propertyEntries,
+    propertyValues,
+  });
+  return {
+    ...canonicalInput,
+    propertyValues: normalized.propertyValues,
+    propertyTypeAssertions: normalized.propertyTypeAssertions,
+  };
+}