Skip to content

Write HTML. Render video. Built for agents.

fix(cli): check waits for late images and runs its browser pass in unnamed macOS sandboxes (#5977)

Miguel Ángelf440db90197b
diff --git a/packages/cli/src/browser/launch.ts b/packages/cli/src/browser/launch.ts
index 97da91edd0..2cda8a9388 100644
--- a/packages/cli/src/browser/launch.ts
+++ b/packages/cli/src/browser/launch.ts
@@ -11,6 +11,7 @@ import { watchChromeTree, type ChromeWatchdog } from "./windowsChromeWatchdog.js
import {
inAgentSandbox,
isOneProcessOverPipe,
+ pipeLaunchClosedOnMac,
machServiceDenied,
oneProcessOverPipe,
sandboxDeniedRemediation,
@@ -89,7 +90,9 @@ export async function launchManagedBrowser(
try {
return await launchOwnedBrowser(puppeteer, sandboxed ? oneProcessOverPipe(options) : options);
} catch (error) {
- const unnamedSeatbelt = !sandboxed && machServiceDenied(normalizeErrorMessage(error));
+ const unnamedSeatbelt =
+ !sandboxed &&
+ (machServiceDenied(normalizeErrorMessage(error)) || pipeLaunchClosedOnMac(error));
if (!unnamedSeatbelt) throw withRemediation(error);
return launchOwnedBrowser(puppeteer, oneProcessOverPipe(options)).catch(
(retryError: unknown) => {
diff --git a/packages/cli/src/browser/sandboxDenied.test.ts b/packages/cli/src/browser/sandboxDenied.test.ts
index a6a1c4848a..4ec29fd0e3 100644
--- a/packages/cli/src/browser/sandboxDenied.test.ts
+++ b/packages/cli/src/browser/sandboxDenied.test.ts
@@ -1,5 +1,11 @@
import { EventEmitter } from "node:events";
-import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core";
+import {
+ ProtocolError,
+ type Browser,
+ type LaunchOptions,
+ type PuppeteerNode,
+} from "puppeteer-core";
+import { TargetCloseError } from "puppeteer-core/internal/common/Errors.js";
import { afterEach, describe, expect, it, vi } from "vitest";
import { launchManagedBrowser } from "./launch.js";
@@ -32,13 +38,13 @@ describe("a browser launch a sandbox refuses", () => {
const fakeBrowser = () => ({ process: () => new EventEmitter() }) as unknown as Browser;
-function recordingPuppeteer(failures: string[]) {
+function recordingPuppeteer(failures: (string | Error)[]) {
const launches: LaunchOptions[] = [];
const puppeteer = {
launch: async (options: LaunchOptions) => {
launches.push(options);
const failure = failures.shift();
- if (failure) throw new Error(failure);
+ if (failure) throw typeof failure === "string" ? new Error(failure) : failure;
return fakeBrowser();
},
} as unknown as PuppeteerNode;
@@ -76,6 +82,38 @@ describe("a browser inside an agent's macOS seatbelt", () => {
"--disable-gpu-compositing",
]);
});
+ it("relaunches as one process when an unnamed sandbox closes a pipe launch before its first targets", async () => {
+ vi.stubEnv("CODEX_SANDBOX", "");
+ Object.defineProperty(process, "platform", { value: "darwin" });
+ const { puppeteer, launches } = recordingPuppeteer([
+ new TargetCloseError("Protocol error (Target.setDiscoverTargets): Target closed"),
+ ]);
+ await expect(launchManagedBrowser(puppeteer, { args: ["--headless"] })).resolves.toBeDefined();
+ expect(launches.map((options) => options.args)).toEqual([
+ ["--headless"],
+ ["--headless", "--single-process", "--disable-gpu-compositing"],
+ ]);
+ });
+
+ it("leaves any other protocol error failed on macOS", async () => {
+ vi.stubEnv("CODEX_SANDBOX", "");
+ Object.defineProperty(process, "platform", { value: "darwin" });
+ const other = new ProtocolError("Protocol error (Target.setDiscoverTargets): Not allowed");
+ const { puppeteer, launches } = recordingPuppeteer([other]);
+ await expect(launchManagedBrowser(puppeteer, { args: ["--headless"] })).rejects.toBe(other);
+ expect(launches).toHaveLength(1);
+ });
+
+ it("leaves a closed pipe launch failed off macOS, where no seatbelt exists", async () => {
+ vi.stubEnv("CODEX_SANDBOX", "");
+ Object.defineProperty(process, "platform", { value: "linux" });
+ const closed = new TargetCloseError(
+ "Protocol error (Target.setDiscoverTargets): Target closed",
+ );
+ const { puppeteer, launches } = recordingPuppeteer([closed]);
+ await expect(launchManagedBrowser(puppeteer, { args: ["--headless"] })).rejects.toBe(closed);
+ expect(launches).toHaveLength(1);
+ });
});
describe("a browser launch that never settles", () => {
diff --git a/packages/cli/src/browser/sandboxDenied.ts b/packages/cli/src/browser/sandboxDenied.ts
index ec629f9b9c..04926b7c3d 100644
--- a/packages/cli/src/browser/sandboxDenied.ts
+++ b/packages/cli/src/browser/sandboxDenied.ts
@@ -8,6 +8,10 @@ export function machServiceDenied(errorMessage: string): boolean {
return MACH_SERVICE_DENIED.test(errorMessage);
}
+export function pipeLaunchClosedOnMac(error: unknown, platform = process.platform): boolean {
+ return platform === "darwin" && error instanceof Error && error.name === "TargetCloseError";
+}
+
/** Codex runs agent commands in a macOS seatbelt, which names itself in the environment. */
export function inAgentSandbox(env = process.env, platform = process.platform): boolean {
return platform === "darwin" && env.CODEX_SANDBOX === "seatbelt";
diff --git a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts
index f896f605d7..fbc7de531f 100644
--- a/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.browserFallback.test.ts
@@ -35,6 +35,7 @@ vi.mock("@hyperframes/engine", () => ({
usesSoftwareWebGpu: mocks.usesSoftwareWebGpu,
DEFAULT_CONFIG: { pageNavigationTimeout: 60_000 },
resolvePageNavigationTimeout: () => 60_000,
+ waitForImagesReady: async () => true,
}));
import { openSettledCompositionPage } from "./captureCompositionFrame.js";
diff --git a/packages/cli/src/capture/captureCompositionFrame.lateImage.browser.test.ts b/packages/cli/src/capture/captureCompositionFrame.lateImage.browser.test.ts
new file mode 100644
index 0000000000..20b6ab06e4
--- /dev/null
+++ b/packages/cli/src/capture/captureCompositionFrame.lateImage.browser.test.ts
@@ -0,0 +1,61 @@
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import sharp from "sharp";
+import { afterAll, beforeAll, expect, it } from "vitest";
+import { openSettledCompositionPage } from "./captureCompositionFrame.js";
+
+// A red image added after load and served past the 1.5 s settle cap: render waits for it, so the
+// settled page every snapshot, compare and check frame is taken from must wait too.
+const IMAGE_MS = 3_000;
+const RED_PNG = Buffer.from(
+ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC",
+ "base64",
+);
+const HTML = `<!doctype html><html><body style="margin:0;background:#000">
+<div id="root" data-composition-id="main" data-width="320" data-height="180" data-duration="1"></div>
+<script>
+ window.__renderReady = true;
+ addEventListener("load", () => {
+ const image = document.createElement("img");
+ image.src = "/late.png";
+ image.style.cssText = "position:absolute;left:0;top:0;width:320px;height:180px";
+ document.getElementById("root").appendChild(image);
+ });
+</script></body></html>`;
+
+let server: Server;
+let url: string;
+
+beforeAll(async () => {
+ server = createServer((req, res) => {
+ if (req.url === "/late.png") {
+ setTimeout(() => res.writeHead(200, { "Content-Type": "image/png" }).end(RED_PNG), IMAGE_MS);
+ return;
+ }
+ res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(HTML);
+ });
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/`;
+});
+
+afterAll(() => {
+ server.closeAllConnections();
+ server.close();
+});
+
+it("waits for an image that lands after the settle cap, as render does", async () => {
+ const { browser, page } = await openSettledCompositionPage(HTML, url, {
+ renderReadyTimeoutMs: 5_000,
+ renderReadyWarningSuffix: "test",
+ browserGpuMode: "software",
+ });
+ try {
+ const frame = await page.screenshot({ type: "png" });
+ const { data, info } = await sharp(frame).raw().toBuffer({ resolveWithObject: true });
+ const center =
+ (Math.floor(info.height / 2) * info.width + Math.floor(info.width / 2)) * info.channels;
+ expect([...data.subarray(center, center + 3)]).toEqual([255, 0, 0]);
+ } finally {
+ await browser.close();
+ }
+}, 90_000);
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index 8d12826676..a06cb22802 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -251,6 +251,13 @@ async function waitForCompositionSettle(
});
await waitForLateSubresources(page, options.lateSubresourceTimeoutMs ?? CAPTURE_SETTLE_MS);
+ const { resolveConfig, waitForImagesReady } = await import("@hyperframes/engine");
+ const imageTimeoutMs = resolveConfig().playerReadyTimeout;
+ await waitForImagesReady(page, imageTimeoutMs, (sources) =>
+ console.warn(
+ ` ${c.warn("⚠")} Some images did not load within ${imageTimeoutMs}ms: ${sources}. They may show blank.`,
+ ),
+ );
return runtimeReady;
}
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index c2a7e2f8cc..5559c948eb 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -143,6 +143,7 @@ export {
type DiscardWarmupInnerCapture,
type StaticVerificationOutcome,
VfxFailureError,
+ waitForImagesReady,
} from "./services/frameCapture.js";
export {
CaptureFailure,
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 18322d63bf..5cac9bcf04 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -2019,6 +2019,30 @@ export async function pollImagesReady(
return check();
}
+export async function waitForImagesReady(
+ page: Page,
+ timeoutMs: number,
+ onUnloaded: (sources: string) => void,
+): Promise<boolean> {
+ const ready = await pollImagesReady(page, timeoutMs);
+ if (!ready) {
+ onUnloaded(
+ await page.evaluate(() =>
+ Array.from(document.querySelectorAll("img"))
+ .filter((img) => {
+ const src = img.getAttribute("src") || "";
+ if (!src || src.startsWith("data:")) return false;
+ return !(img.complete && img.naturalWidth > 0);
+ })
+ .map((img) => img.src || img.getAttribute("src") || "(no src)")
+ .join(", "),
+ ),
+ );
+ }
+ await decodeAllImages(page);
+ return ready;
+}
+
type MediaReadinessSnapshot = {
pendingImages: string[];
failedImages: string[];
@@ -2513,27 +2537,12 @@ export async function initializeSession(session: CaptureSession): Promise<void>
const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
const [videosReady] = await Promise.all([
pollVideosReady(page, skipVideoIds, pageReadyTimeout),
- pollImagesReady(page, pageReadyTimeout).then(async (ready) => {
- if (!ready) {
- const failedImages = await page.evaluate(() => {
- return Array.from(document.querySelectorAll("img"))
- .filter((img) => {
- const ie = img as HTMLImageElement;
- const src = ie.getAttribute("src") || "";
- if (!src || src.startsWith("data:")) return false;
- return !(ie.complete && ie.naturalWidth > 0);
- })
- .map((img) => (img as HTMLImageElement).src || img.getAttribute("src") || "(no src)")
- .join(", ");
- });
- console.warn(
- `[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
- `Continuing render. Affected images may appear blank/missing in early frames.`,
- );
- }
- await decodeAllImages(page);
- return ready;
- }),
+ waitForImagesReady(page, pageReadyTimeout, (failedImages) =>
+ console.warn(
+ `[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
+ `Continuing render. Affected images may appear blank/missing in early frames.`,
+ ),
+ ),
page.evaluate(`document.fonts?.ready`),
waitForOptionalTailwindReady(page, pageReadyTimeout),
]);
@@ -2669,27 +2678,12 @@ export async function initializeSession(session: CaptureSession): Promise<void>
const bfSkipVideoIds = session.options.skipReadinessVideoIds ?? [];
const [bfVideosReady] = await Promise.all([
pollVideosReady(page, bfSkipVideoIds, pageReadyTimeout),
- pollImagesReady(page, pageReadyTimeout).then(async (ready) => {
- if (!ready) {
- const failedImages = await page.evaluate(() => {
- return Array.from(document.querySelectorAll("img"))
- .filter((img) => {
- const ie = img as HTMLImageElement;
- const src = ie.getAttribute("src") || "";
- if (!src || src.startsWith("data:")) return false;
- return !(ie.complete && ie.naturalWidth > 0);
- })
- .map((img) => (img as HTMLImageElement).src || img.getAttribute("src") || "(no src)")
- .join(", ");
- });
- console.warn(
- `[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
- `Continuing render. Affected images may appear blank/missing in early frames.`,
- );
- }
- await decodeAllImages(page);
- return ready;
- }),
+ waitForImagesReady(page, pageReadyTimeout, (failedImages) =>
+ console.warn(
+ `[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
+ `Continuing render. Affected images may appear blank/missing in early frames.`,
+ ),
+ ),
page.evaluate(`document.fonts?.ready`),
waitForOptionalTailwindReady(page, pageReadyTimeout),
]);