@agent-native/core 0.81.2 → 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: 4803
+- template files: 4807

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @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
+
+- 3807702: Fix MCP App embed rendering in ChatGPT/Codex hosts:
+  - Stop the `openai:set_globals` storm that left embeds stuck blanking by
+    guarding the bridge sync on a signature that ignores host `maxHeight`, and
+    by not re-blanking once the app frame has launched.
+  - Size embeds to their content: the embedded app reports its real
+    `scrollHeight` via `agentNative.contentHeight` and the shell sizes the iframe
+    to that (plus chrome) instead of the host max, so plans no longer render far
+    too tall or too short.
+  - Suppress empty embeds: when a tool whose descriptor declares an embed widget
+    produces no embeddable content, the result is marked `isError` so the host
+    shows the text result without an empty widget box. This also keeps read-only
+    and comment-mutation tools from rendering an embed for results that produce
+    no plan surface.
+  - Bump the embed shell resource version so hosts refetch the updated shell.
+
 ## 0.81.2
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.81.2",
+  "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/client/frame.ts

@@ -83,6 +83,60 @@ export function isTrustedFrameMessage(event: MessageEvent): boolean {
   return event.source === window.parent || event.source === window;
 }
 
+// ---------------------------------------------------------------------------
+// Content-height reporting (for MCP App embeds)
+// ---------------------------------------------------------------------------
+//
+// The embed shell renders this app in a cross-origin iframe and can't measure
+// its content, so we post the real content height for the shell to size to.
+// Only shrinks when the document flows to its natural height — embed layouts
+// must not force `100vh`/`h-screen` on the root, or scrollHeight just equals
+// the iframe height.
+let _contentHeightReportingStarted = false;
+let _lastReportedContentHeight = 0;
+
+function measureContentHeight(): number {
+  if (typeof document === "undefined") return 0;
+  const doc = document.documentElement;
+  const body = document.body;
+  return Math.ceil(
+    Math.max(doc ? doc.scrollHeight : 0, body ? body.scrollHeight : 0),
+  );
+}
+
+function reportContentHeight(): void {
+  if (typeof window === "undefined" || window.parent === window) return;
+  const height = measureContentHeight();
+  if (!height || Math.abs(height - _lastReportedContentHeight) < 2) return;
+  _lastReportedContentHeight = height;
+  sendToFrame("agentNative.contentHeight", { height });
+}
+
+function startContentHeightReporting(): void {
+  if (_contentHeightReportingStarted || typeof window === "undefined") return;
+  if (window.parent === window) return;
+  _contentHeightReportingStarted = true;
+  let scheduled = false;
+  const schedule = () => {
+    if (scheduled) return;
+    scheduled = true;
+    window.requestAnimationFrame(() => {
+      scheduled = false;
+      reportContentHeight();
+    });
+  };
+  schedule();
+  for (const delay of [100, 300, 800, 1500]) window.setTimeout(schedule, delay);
+  try {
+    const observer = new ResizeObserver(schedule);
+    if (document.documentElement) observer.observe(document.documentElement);
+    if (document.body) observer.observe(document.body);
+  } catch {
+    window.addEventListener("resize", schedule, { passive: true });
+  }
+  window.addEventListener("load", schedule, { passive: true });
+}
+
 // Listen for frame origin message and cache it.
 // Only accept from the direct parent frame, and only set once.
 if (typeof window !== "undefined") {
@@ -102,6 +156,7 @@ if (typeof window !== "undefined") {
         { type: "agentNative.embeddedAppReady" },
         getFramePostMessageTargetOrigin() ?? window.location.origin,
       );
+      startContentHeightReporting();
     }
   });
 }

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/core/src/mcp/build-server.ts

@@ -448,6 +448,18 @@ function purgeEmbedStartUrls(value: unknown, depth = 0): unknown {
   return value;
 }
 
+// True when a tool result carries SOME content. An errored/no-plan result comes
+// back empty (`{}` / null) and would render an empty embed box. We gate on "has
+// content", not "has a URL" — valid embeds often carry data but no URL (the
+// shell mints the embed-start itself).
+function mcpResultHasContent(result: unknown): boolean {
+  if (result == null) return false;
+  if (typeof result === "string") return result.trim().length > 0;
+  if (Array.isArray(result)) return result.length > 0;
+  if (typeof result === "object") return Object.keys(result).length > 0;
+  return Boolean(result);
+}
+
 function mcpAppEmbedOpenLinkMeta(
   result: unknown,
   resource: ResolvedMcpAppResource,
@@ -750,7 +762,7 @@ function safeUiSegment(value: string | undefined, fallback: string): string {
 
 // ChatGPT and Claude cache MCP App resource HTML by `ui://` URI. Bump this
 // when the shared shell changes in a way that must invalidate host caches.
-const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v54";
+const MCP_APP_RESOURCE_SHELL_VERSION = "shell-v64";
 
 function legacyDefaultMcpAppUri(config: MCPConfig, actionName: string): string {
   const app = safeUiSegment(config.appId ?? config.name, "agent-native");
@@ -1546,12 +1558,24 @@ export async function createMCPServerForRequest(
         // branch below degrades to the plain deep-link artifacts the tool would
         // otherwise return — no `openai/outputTemplate`, no minted embed-start,
         // no embed structuredContent — so the host shows a link, not an iframe.
-        const mcpAppResource = requestMeta?.inlineMcpApps
+        const mcpAppResourceCandidate = requestMeta?.inlineMcpApps
           ? await resolveMcpAppResourceSafely(config, name, entry, requestMeta)
           : null;
-        const rawResultForClient = mcpAppResource
+        const rawResultForClient = mcpAppResourceCandidate
           ? await withServerMintedMcpAppEmbedStart(rawResult, requestMeta)
           : rawResult;
+        // Only attach the embed widget for a non-error result that has content.
+        const embedHasContent = mcpResultHasContent(rawResultForClient);
+        const mcpAppResource =
+          mcpAppResourceCandidate && !mcpResultIsError && embedHasContent
+            ? mcpAppResourceCandidate
+            : null;
+        // `openai/outputTemplate` is declared at the tool level, so the host
+        // renders a widget for every call regardless of result _meta. The only
+        // per-result signal it honors is `isError` (shows error text, no widget),
+        // so treat an embed tool that produced nothing as an error.
+        const embedProducedNothing =
+          !!mcpAppResourceCandidate && !mcpResultIsError && !embedHasContent;
         const { block, _meta } = buildLinkArtifacts(
           entry,
           (args as Record<string, any>) ?? {},
@@ -1590,7 +1614,9 @@ export async function createMCPServerForRequest(
         if (block) content.push(block);
         return {
           content,
-          ...(mcpResultIsError ? { isError: true } : {}),
+          ...(mcpResultIsError || embedProducedNothing
+            ? { isError: true }
+            : {}),
           ...(structuredContent ? { structuredContent } : {}),
           ...(Object.keys(responseMeta).length > 0
             ? { _meta: responseMeta }

package/corpus/core/src/mcp/embed-app.ts

@@ -138,6 +138,7 @@ export function embedApp(
     let appFrameLoadTimer = null;
     let lastFrameSrc = "";
     let embedSessionRefreshAttempts = 0;
+    let reportedContentHeight = 0;
 
     function esc(value) {
       return String(value ?? "")
@@ -174,10 +175,18 @@ export function embedApp(
     function visibleIntrinsicHeight() {
       const context = hostState().context || {};
       const hostMaxHeight = contextMaxHeight(context);
+      // Size to the app-reported content height (the shell can't measure the
+      // cross-origin frame). Don't clamp to the host maxHeight — on Codex it's a
+      // small inline hint (~360) that clips the plan; applyIntrinsicHeight still
+      // caps at defaultIntrinsicHeight.
+      if (reportedContentHeight > 0) {
+        return Math.floor(reportedContentHeight + chromeHeight);
+      }
       if (hostMaxHeight) return Math.floor(hostMaxHeight);
-      const viewportHeight = finiteNumber(window.visualViewport && window.visualViewport.height) ||
-        finiteNumber(window.innerHeight);
-      return Math.floor(viewportHeight || defaultIntrinsicHeight);
+      // No host maxHeight and no content height yet: use the CONFIGURED height,
+      // never window.innerHeight. Echoing the iframe's own size pins us to the
+      // current frame height (circular) and locks the embed at the cap forever.
+      return Math.floor(defaultIntrinsicHeight);
     }
 
     function applyIntrinsicHeight(nextHeight) {
@@ -1356,7 +1365,8 @@ export function embedApp(
     }
 
     function notifyHostHeight() {
-      const height = applyIntrinsicHeight(visibleIntrinsicHeight());
+      const intrinsic = visibleIntrinsicHeight();
+      const height = applyIntrinsicHeight(intrinsic);
       if (!openAiBridge || typeof openAiBridge.notifyIntrinsicHeight !== "function") {
         if (app && typeof app.sendSizeChanged === "function") {
           try {
@@ -1487,6 +1497,14 @@ export function embedApp(
         notifyOuterMcpAppReady();
         return;
       }
+      if (event.data.type === "agentNative.contentHeight") {
+        const next = finiteNumber(data && data.height);
+        if (next && Math.abs(next - reportedContentHeight) >= 1) {
+          reportedContentHeight = next;
+          notifyHostHeightSoon();
+        }
+        return;
+      }
       if (event.data.type === "agentNative.embedSessionExpired") {
         refreshExpiredEmbedSession();
         return;
@@ -1538,12 +1556,9 @@ export function embedApp(
         const selfNavigate = shouldSelfNavigateToApp();
         if (startedFor === launchUrl) return;
         startedFor = launchUrl;
-        // Only show the loading message when no frame is mounted yet. ChatGPT
-        // fires openai:set_globals (and thus re-launch) constantly; calling
-        // setMessage() unconditionally here wiped the just-mounted iframe out of
-        // the stage on every redundant launch, so the app rendered and was
-        // instantly blanked back to "Loading app" forever. renderFrame()/
-        // transplant replace the stage themselves when they actually (re)mount.
+        // Only show "Loading app" when no frame is mounted. set_globals
+        // re-launches constantly, so calling it every time would wipe the
+        // just-mounted iframe; renderFrame/transplant own the stage on (re)mount.
         if (!appFrame) {
           setMessage("Loading app");
         }
@@ -1671,14 +1686,11 @@ export function embedApp(
       toolResultData = objectValue(data);
       openUrl = openLinkFrom(params, data);
       openStartUrl = embedStartUrlFrom(params, data);
-      // ChatGPT/Codex fire openai:set_globals extremely often, and the listener
-      // that calls this re-syncs on each one. Because this function calls
-      // notifyHostHeight()/sendHostContext() (which the host reflects back as a
-      // fresh set_globals), an unguarded sync becomes an infinite feedback storm
-      // that starves the host until it shows its sad-face placeholder. Only do
-      // the host round-trips + (re)launch when something we care about changed.
-      // Deliberately EXCLUDE bridge.maxHeight: the host mutates it on every
-      // set_globals as it echoes our height back, which would defeat the guard.
+      // set_globals fires constantly, and this sync calls notifyHostHeight/
+      // sendHostContext which the host echoes back as another set_globals — an
+      // infinite storm. Only do the host round-trips + (re)launch when something
+      // we care about changed. Exclude maxHeight: the host mutates it every
+      // event, which would defeat the guard.
       let signature;
       try {
         signature = JSON.stringify([
@@ -1704,6 +1716,9 @@ export function embedApp(
       if (openUrl || openStartUrl) {
         void launchEmbed();
       } else if (!appFrame) {
+        // No open URL yet — a content-less result no longer reaches the host as
+        // a widget (build-server marks it isError), so this is the transient
+        // "waiting for the embed to resolve" state, not an empty box.
         setMessage("Waiting for app result");
       }
       return true;