@agent-native/core 0.81.3 → 0.82.0

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2043
-- template files: 4804
+- template files: 4807

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.82.0
+
+### Minor Changes
+
+- fe9fd99: Add optional `resumable` capability to `FileUploadProvider` for streaming uploads. Providers that implement `startSession`, `relayChunk`, and `completeSession` can receive video chunks during recording instead of waiting for a fully assembled file after stop. The Builder.io provider implements this via the GCS resumable upload protocol. Also exports `ResumableUploadSession` and `ResumableChunkResult` types.
+
 ## 0.81.3
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.81.3",
+  "version": "0.82.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/file-upload/builder.ts

@@ -2,6 +2,8 @@ import type {
   FileUploadProvider,
   FileUploadInput,
   FileUploadResult,
+  ResumableUploadSession,
+  ResumableChunkResult,
 } from "./types.js";
 
 const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
@@ -46,8 +48,6 @@ async function uploadLargeFileViaSignedUrl(
   bareMimeType: string,
   bytes: Uint8Array,
 ): Promise<FileUploadResult> {
-  const host = builderUploadHost();
-  const authHeader = { Authorization: `Bearer ${privateKey}` };
   const name = input.filename ?? "upload";
   const mb = (bytes.byteLength / (1024 * 1024)).toFixed(1);
 
@@ -57,32 +57,12 @@ async function uploadLargeFileViaSignedUrl(
 
   // Step 1 — request a signed URL.
   console.log(`[builder-upload] step 1: requesting signed URL`);
-  const step1Res = await fetchWithTimeout(
-    new URL("/api/v1/upload/signed-url", host).toString(),
-    {
-      method: "POST",
-      headers: { ...authHeader, "Content-Type": "application/json" },
-      body: JSON.stringify({
-        fileName: name,
-        contentType: bareMimeType,
-        size: bytes.byteLength,
-      }),
-    },
+  const { uploadUrl, assetId, requiredHeaders } = await requestBuilderSignedUrl(
+    privateKey,
+    name,
+    bareMimeType,
+    bytes.byteLength,
   );
-  await assertOk(step1Res, "Builder.io signed-URL request failed");
-
-  const step1Json = (await step1Res.json()) as {
-    uploadUrl?: string;
-    assetId?: string;
-    expiresAt?: string;
-    requiredHeaders?: Record<string, string>;
-  };
-  const { uploadUrl, assetId, requiredHeaders } = step1Json;
-  if (!uploadUrl || !assetId || !requiredHeaders) {
-    throw new Error(
-      `Builder.io signed-URL response missing required fields: ${JSON.stringify(Object.keys(step1Json))}`,
-    );
-  }
   console.log(`[builder-upload] step 1 ok: assetId=${assetId}`);
 
   // Step 2 — PUT bytes directly to GCS. Only requiredHeaders; no Authorization
@@ -102,21 +82,80 @@ async function uploadLargeFileViaSignedUrl(
   console.log(
     `[builder-upload] step 3: registering asset - ${assetId}, ${input.filename}`,
   );
-  const step3Res = await fetchWithTimeout(
+  const { url, id } = await completeBuilderUpload(
+    privateKey,
+    assetId,
+    input.filename,
+  );
+  console.log(`[builder-upload] done [${assetId}]: ${url}`);
+  return { url, id, provider: "builder" };
+}
+
+async function requestBuilderSignedUrl(
+  privateKey: string,
+  filename: string,
+  mimeType: string,
+  size: number,
+  resumable = false,
+): Promise<{
+  uploadUrl: string;
+  assetId: string;
+  requiredHeaders: Record<string, string>;
+}> {
+  const host = builderUploadHost();
+  const url = new URL("/api/v1/upload/signed-url", host);
+  const res = await fetchWithTimeout(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${privateKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      fileName: filename,
+      contentType: mimeType,
+      size,
+      resumable,
+    }),
+  });
+  await assertOk(res, "Builder.io signed-URL request failed");
+  const json = (await res.json()) as {
+    uploadUrl?: string;
+    assetId?: string;
+    requiredHeaders?: Record<string, string>;
+  };
+  if (!json.uploadUrl || !json.assetId || !json.requiredHeaders) {
+    throw new Error(
+      `Builder.io signed-URL response missing required fields: ${JSON.stringify(Object.keys(json))}`,
+    );
+  }
+  return {
+    uploadUrl: json.uploadUrl,
+    assetId: json.assetId,
+    requiredHeaders: json.requiredHeaders,
+  };
+}
+
+async function completeBuilderUpload(
+  privateKey: string,
+  assetId: string,
+  filename: string | undefined,
+): Promise<{ url: string; id?: string }> {
+  const host = builderUploadHost();
+  const res = await fetchWithTimeout(
     new URL("/api/v1/upload/complete", host).toString(),
     {
       method: "POST",
-      headers: { ...authHeader, "Content-Type": "application/json" },
-      body: JSON.stringify({ assetId, name: input.filename }),
+      headers: {
+        Authorization: `Bearer ${privateKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ assetId, name: filename }),
     },
   );
-  await assertOk(step3Res, "Builder.io upload complete failed");
-
-  const { url, id } = (await step3Res.json()) as { url?: string; id?: string };
-  if (!url) throw new Error("Builder.io upload/complete returned no URL");
-
-  console.log(`[builder-upload] done [${assetId}]: ${url}`);
-  return { url, id, provider: "builder" };
+  await assertOk(res, "Builder.io upload complete failed");
+  const json = (await res.json()) as { url?: string; id?: string };
+  if (!json.url) throw new Error("Builder.io upload/complete returned no URL");
+  return { url: json.url, id: json.id };
 }
 
 // Retry transient 5xx once with backoff. Builder.io's upload service
@@ -221,4 +260,127 @@ export const builderFileUploadProvider: FileUploadProvider = {
     console.log(`[builder-upload] done: ${json.url}`);
     return { url: json.url, id: json.id, provider: "builder" };
   },
+
+  resumable: {
+    async startSession(filename, mimeType, maxBytes) {
+      const { resolveBuilderPrivateKey } =
+        await import("../server/credential-provider.js");
+      const privateKey = await resolveBuilderPrivateKey();
+      if (!privateKey) throw new Error("BUILDER_PRIVATE_KEY is not set");
+
+      console.log(
+        `[builder-resumable] starting session: ${filename} ${mimeType} ${maxBytes} bytes`,
+      );
+      const { uploadUrl, assetId, requiredHeaders } =
+        await requestBuilderSignedUrl(
+          privateKey,
+          filename,
+          mimeType,
+          maxBytes,
+          true,
+        );
+      console.log(`[builder-resumable] session step 1 ok: assetId=${assetId}`);
+
+      const initHeaders: Record<string, string> = {
+        "Content-Type": mimeType,
+        "x-goog-resumable": "start",
+      };
+      const contentLengthRange =
+        requiredHeaders?.["x-goog-content-length-range"];
+      if (contentLengthRange)
+        initHeaders["x-goog-content-length-range"] = contentLengthRange;
+
+      console.log(`[builder-resumable] session step 2: initiating GCS session`);
+      const initRes = await fetchWithTimeout(uploadUrl, {
+        method: "POST",
+        headers: initHeaders,
+        body: new Uint8Array(0),
+      });
+      if (!initRes.ok) {
+        const body = await initRes.text().catch(() => "");
+        throw new Error(
+          `GCS resumable session initiation failed (${initRes.status}): ${body}`,
+        );
+      }
+      const sessionUri = initRes.headers.get("location");
+      if (!sessionUri)
+        throw new Error(
+          "GCS did not return a Location header for the resumable session",
+        );
+
+      console.log(`[builder-resumable] session ready: assetId=${assetId}`);
+      return {
+        sessionId: sessionUri,
+        meta: { assetId, filename, mimeType },
+      } satisfies ResumableUploadSession;
+    },
+
+    async relayChunk(session, contentRange, bytes, options) {
+      const sessionUri = session.sessionId;
+      const MAX_ATTEMPTS = 4;
+      const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+      const delayMs = (attempt: number) =>
+        Math.min(2000, 300 * 2 ** (attempt - 1));
+
+      let lastError: unknown = null;
+      for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+          const headers: Record<string, string> = {
+            "Content-Range": contentRange,
+          };
+          if (options?.mimeType) headers["Content-Type"] = options.mimeType;
+          const res = await fetch(sessionUri, {
+            method: "PUT",
+            headers,
+            body: bytes as unknown as BodyInit,
+          });
+          if (res.status === 308 || res.ok)
+            return {
+              ok: true,
+              status: res.status,
+            } satisfies ResumableChunkResult;
+          if (RETRYABLE.has(res.status) && attempt < MAX_ATTEMPTS) {
+            await res.text().catch(() => "");
+            console.warn(
+              `[builder-resumable] transient ${res.status} on attempt ${attempt}, retrying`,
+            );
+            await new Promise((r) => setTimeout(r, delayMs(attempt)));
+            continue;
+          }
+          return {
+            ok: false,
+            status: res.status,
+          } satisfies ResumableChunkResult;
+        } catch (err) {
+          lastError = err;
+          if (attempt >= MAX_ATTEMPTS) break;
+          console.warn(
+            `[builder-resumable] network error on attempt ${attempt}:`,
+            err instanceof Error ? err.message : String(err),
+          );
+          await new Promise((r) => setTimeout(r, delayMs(attempt)));
+        }
+      }
+      throw lastError instanceof Error
+        ? lastError
+        : new Error("GCS PUT failed after retries");
+    },
+
+    async completeSession(session, filename) {
+      const { resolveBuilderPrivateKey } =
+        await import("../server/credential-provider.js");
+      const privateKey = await resolveBuilderPrivateKey();
+      if (!privateKey) throw new Error("BUILDER_PRIVATE_KEY is not set");
+
+      const assetId = session.meta.assetId as string;
+      console.log(`[builder-resumable] completing upload: assetId=${assetId}`);
+      const { url } = await completeBuilderUpload(
+        privateKey,
+        assetId,
+        filename,
+      );
+      console.log(`[builder-resumable] upload complete: ${url}`);
+      return url;
+    },
+  },
 };

package/corpus/core/src/file-upload/index.ts

@@ -2,6 +2,8 @@ export type {
   FileUploadInput,
   FileUploadProvider,
   FileUploadResult,
+  ResumableUploadSession,
+  ResumableChunkResult,
 } from "./types.js";
 export {
   registerFileUploadProvider,

package/corpus/core/src/file-upload/types.ts

@@ -27,6 +27,22 @@ export interface FileUploadResult {
   provider: string;
 }
 
+/** Opaque session handle returned by {@link FileUploadProvider.resumable.startSession}.
+ * `sessionId` is provider-specific (GCS Location URI, S3 UploadId, etc.).
+ * `meta` holds any provider state needed for subsequent relay and complete calls. */
+export interface ResumableUploadSession {
+  sessionId: string;
+  meta: Record<string, unknown>;
+}
+
+export interface ResumableChunkResult {
+  ok: boolean;
+  status: number;
+  /** Providers that need per-chunk state (e.g. S3 ETags) return updated meta
+   * here; the chunk route merges it back into the stored session. */
+  updatedMeta?: Record<string, unknown>;
+}
+
 export interface FileUploadProvider {
   /** Unique id, e.g. "builder", "s3". */
   id: string;
@@ -41,4 +57,26 @@ export interface FileUploadProvider {
   isConfiguredForRequest?: () => Promise<boolean>;
   /** Upload a file and return a URL. Throw on failure. */
   upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+  /**
+   * Optional resumable/streaming upload capability.
+   * When present, create-recording will initialise a session and stream chunks
+   * during recording instead of assembling the full blob after stop().
+   */
+  resumable?: {
+    startSession(
+      filename: string,
+      mimeType: string,
+      maxBytes: number,
+    ): Promise<ResumableUploadSession>;
+    relayChunk(
+      session: ResumableUploadSession,
+      contentRange: string,
+      bytes: Uint8Array,
+      options?: { mimeType?: string },
+    ): Promise<ResumableChunkResult>;
+    completeSession(
+      session: ResumableUploadSession,
+      filename: string,
+    ): Promise<string>;
+  };
 }

package/corpus/templates/clips/actions/create-recording.ts

@@ -11,6 +11,9 @@
 
 import { defineAction } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
+import { getActiveFileUploadProviderForRequest } from "@agent-native/core/file-upload";
+import type { UploadMode } from "@shared/recording-core.js";
+import { MAX_UPLOAD_BYTES } from "@shared/upload-limits.js";
 
 import { getDb, schema } from "../server/db/index.js";
 import {
@@ -19,6 +22,7 @@ import {
   requireOrganizationAccess,
   stringifySpaceIds,
 } from "../server/lib/recordings.js";
+import { setResumableSession } from "../server/lib/resumable-session.js";
 import { createRecordingSchema } from "./lib/create-recording-schema.js";
 import { DEFAULT_RECORDING_TITLE } from "./lib/title-source.js";
 
@@ -76,6 +80,45 @@ export default defineAction({
 
     console.log(`Created recording "${title}" (${id})`);
 
+    // Initialize a resumable upload session so chunks are streamed to the
+    // provider during recording (no post-stop assembly). Falls back gracefully
+    // to the SQL chunk path when no provider supports resumable uploads or the
+    // init fails.
+    let uploadMode: UploadMode = "buffered";
+    const uploadProvider = await getActiveFileUploadProviderForRequest();
+    if (args.requestStreaming && uploadProvider?.resumable) {
+      try {
+        const recordingMimeType =
+          args.mimeType?.split(";")[0]?.trim() || "video/webm";
+        const ext = /mp4|quicktime/i.test(recordingMimeType) ? "mp4" : "webm";
+        const filename = `${id}.${ext}`;
+        console.log(
+          `[create-recording] starting resumable session: provider=${uploadProvider.id} mimeType=${recordingMimeType}`,
+        );
+        const session = await uploadProvider.resumable.startSession(
+          filename,
+          recordingMimeType,
+          MAX_UPLOAD_BYTES,
+        );
+        await setResumableSession(id, {
+          providerId: uploadProvider.id,
+          sessionId: session.sessionId,
+          meta: session.meta,
+          bytesUploaded: 0,
+          lastCommittedIndex: -1,
+        });
+        uploadMode = "streaming";
+        console.log(
+          `[create-recording] resumable session ready for ${id}: provider=${uploadProvider.id}`,
+        );
+      } catch (err) {
+        console.warn(
+          `[create-recording] resumable session init failed, falling back to buffered:`,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+
     return {
       id,
       organizationId,
@@ -84,6 +127,7 @@ export default defineAction({
       abortUrl: `/api/uploads/${id}/abort`,
       // Frontend substitutes {index}/{total}/{isFinal}
       uploadChunkUrlTemplate: `/api/uploads/${id}/chunk?index={index}&total={total}&isFinal={isFinal}`,
+      uploadMode,
     };
   },
 });