@playdrop/playdrop-cli 0.17.19 → 0.17.21

package/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.17.19",
+  "version": "0.17.21",
   "build": 1,
-  "runtimeSdkVersion": "0.17.19",
+  "runtimeSdkVersion": "0.17.21",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/dist/apps/loadCheck.d.ts

@@ -1,8 +1,9 @@
 import type { ApiClient } from "@playdrop/api-client";
 import { type AppPlaytestTape, type AppPlaytestTapeEvent, type AppSurface, type AppUploadCausalComparison, type AppUploadMachineCausalEvidence, type DevGameServerCredentialResponse, type UserResponse } from "@playdrop/types";
-import type { BrowserContextOptions, Frame, Page } from "playwright-core";
+import type { Browser, BrowserContextOptions, Frame, Page } from "playwright-core";
 import type { AppTask } from "../catalogue";
 import { type TaskCaptureSession } from "../appUrls";
+import type { GameServerBuild } from "./serverBuild";
 export { PLAYDROP_SURFACE_CONTEXT_OPTIONS } from "./surfaceProfiles";
 export type HostedLoadCheckResult = {
     status: "PASSED" | "FAILED";
@@ -54,7 +55,7 @@ export declare function verifyHostedEditorPhaseRoundTrip(page: Pick<Page, "evalu
 export declare function formatHostedLoadCheckFailure(taskName: string, result: HostedLoadCheckResult, scope?: "local" | "staged" | "editor" | "final"): string;
 export declare function redactHostedLoadCheckSecrets(text: string, sourceUrl: string): string;
 export declare function formatMountedDevRuntimeFailure(error: unknown): Error;
-export declare function runLocalHostedLoadCheck(input: {
+export type LocalHostedLoadCheckBaseInput = {
     client: ApiClient;
     apiBase: string;
     webBase: string | null | undefined;
@@ -66,12 +67,20 @@ export declare function runLocalHostedLoadCheck(input: {
     currentUser?: UserResponse | null;
     captureSession?: TaskCaptureSession | null;
     allowUnregisteredViewerLaunch?: boolean;
+    gameServerCredential?: DevGameServerCredentialResponse | null;
+    gameServerBuild?: GameServerBuild | null;
+};
+export type LocalHostedLoadCheckRunInput = {
     screenshotPath?: string | null;
     surface?: AppSurface;
     playtestTape?: AppPlaytestTape;
     postReadyWaitMs?: number;
-    gameServerCredential?: DevGameServerCredentialResponse | null;
-}): Promise<HostedLoadCheckResult>;
+};
+export type LocalHostedLoadCheckInput = LocalHostedLoadCheckBaseInput & LocalHostedLoadCheckRunInput;
+export declare function runLocalHostedLoadCheck(input: LocalHostedLoadCheckInput): Promise<HostedLoadCheckResult>;
+export declare function runLocalHostedLoadCheckSequence(input: LocalHostedLoadCheckBaseInput & {
+    checks: LocalHostedLoadCheckRunInput[];
+}): Promise<HostedLoadCheckResult[]>;
 export declare function buildUploadedHostedLoadCheckUrl(rawUrl: string, phase?: "play" | "editor", localDevPort?: number): string;
 export declare function buildUploadedHostedLoadCheckScreenshotPath(task: Pick<AppTask, "name" | "projectDir">, sessionId: string, phase?: "play" | "editor"): string | null;
 export declare function runUploadedHostedLoadCheck(input: {
@@ -91,6 +100,7 @@ export declare function runUploadedHostedLoadCheck(input: {
     postReadyWaitMs?: number;
     phase?: "play" | "editor";
     verifyEditorPhaseRoundTrip?: boolean;
+    installedChromeBrowser?: Browser;
 }): Promise<HostedLoadCheckResult>;
 export declare function comparePlaytestFrames(firstPath: string, secondPath: string, thresholds?: {
     meanDeltaMin: number;

package/dist/apps/loadCheck.js

@@ -21,6 +21,7 @@ exports.formatHostedLoadCheckFailure = formatHostedLoadCheckFailure;
 exports.redactHostedLoadCheckSecrets = redactHostedLoadCheckSecrets;
 exports.formatMountedDevRuntimeFailure = formatMountedDevRuntimeFailure;
 exports.runLocalHostedLoadCheck = runLocalHostedLoadCheck;
+exports.runLocalHostedLoadCheckSequence = runLocalHostedLoadCheckSequence;
 exports.buildUploadedHostedLoadCheckUrl = buildUploadedHostedLoadCheckUrl;
 exports.buildUploadedHostedLoadCheckScreenshotPath = buildUploadedHostedLoadCheckScreenshotPath;
 exports.runUploadedHostedLoadCheck = runUploadedHostedLoadCheck;
@@ -935,7 +936,7 @@ async function runHostedLoadCheck(options) {
         }, {
             ...options.contextOptions,
             automationOrigin: new URL(options.targetUrl).origin,
-        });
+        }, options.installedChromeBrowser);
     }
     catch (error) {
         const launchFailureMessage = redactReportText(error instanceof Error ? error.message : String(error));
@@ -1014,6 +1015,7 @@ async function startOrReuseMountedDevRuntime(input) {
                 credential: input.gameServerCredential,
                 platformApiUrl: input.apiBase,
                 publicAddress: `${roomsUrl.host}${roomsUrl.pathname.replace(/\/$/u, "")}`,
+                gameServerBuild: input.gameServerBuild ?? undefined,
             });
         }
         const handle = await (0, devServer_1.startDevServer)({
@@ -1044,116 +1046,152 @@ function formatMountedDevRuntimeFailure(error) {
     }
     return error instanceof Error ? error : new Error(message);
 }
-async function runLocalHostedLoadCheck(input) {
-    let mountedRuntime = null;
-    try {
-        mountedRuntime = await startOrReuseMountedDevRuntime({
-            client: input.client,
-            apiBase: input.apiBase,
-            creatorUsername: input.creatorUsername,
-            task: input.task,
-            devRouterPort: input.devRouterPort,
-            gameServerCredential: input.gameServerCredential,
+async function runLocalHostedLoadCheckAgainstMountedRuntime(input, mountedRuntime, installedChromeBrowser) {
+    const localDevPort = input.devRouterPort === undefined || input.devRouterPort === devServer_1.DEV_ROUTER_PORT ? null : input.devRouterPort;
+    const localAppMetadata = mountedRuntime.runtimeAssetManifest.response.localAppMetadata;
+    const declaredSurfaces = normalizeLoadCheckSurfaceTargets(localAppMetadata.surfaceTargets);
+    const captureSurface = input.surface ?? resolveLoadCheckSurface(localAppMetadata.surfaceTargets, input.task.primarySurface);
+    if (!declaredSurfaces.includes(captureSurface)) {
+        return buildFailedLoadCheckResult("surface_unsupported", `Surface ${captureSurface} is not declared in surfaceTargets for "${input.task.name}".`, null);
+    }
+    const contextOptions = cloneLoadCheckContextOptions(captureSurface);
+    const anonymousExpectedState = resolveAnonymousHostedLaunchState({
+        ...localAppMetadata,
+        captureSurface,
+    });
+    if (input.captureSession) {
+        return await runHostedLoadCheck({
+            targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
+                creatorUsername: input.creatorUsername,
+                appName: input.task.name,
+                appType: input.task.type ?? "GAME",
+                devAuth: "player",
+                player: "1",
+                launchCheck: true,
+                localDevPort,
+                captureSession: input.captureSession,
+            }),
+            timeoutMs: input.timeoutMs,
+            expectedHostedLaunchState: resolvePostAuthHostedLaunchState(localAppMetadata.controllerMode),
+            contextOptions,
+            screenshotPath: input.screenshotPath,
+            playtestTape: input.playtestTape,
+            playtestSurface: captureSurface,
+            postReadyWaitMs: input.postReadyWaitMs,
+            installedChromeBrowser,
         });
-        const localDevPort = input.devRouterPort === undefined || input.devRouterPort === devServer_1.DEV_ROUTER_PORT ? null : input.devRouterPort;
-        const localAppMetadata = mountedRuntime.runtimeAssetManifest.response.localAppMetadata;
-        const declaredSurfaces = normalizeLoadCheckSurfaceTargets(localAppMetadata.surfaceTargets);
-        const captureSurface = input.surface ?? resolveLoadCheckSurface(localAppMetadata.surfaceTargets, input.task.primarySurface);
-        if (!declaredSurfaces.includes(captureSurface)) {
-            return buildFailedLoadCheckResult("surface_unsupported", `Surface ${captureSurface} is not declared in surfaceTargets for "${input.task.name}".`, null);
+    }
+    if (anonymousExpectedState === "login_required") {
+        const registeredApp = await (0, registration_1.fetchRegisteredAppShell)(input.client, input.creatorUsername, input.task.name);
+        const canLaunchUnregisteredViewer = input.allowUnregisteredViewerLaunch === true && Boolean(input.token) && Boolean(input.currentUser);
+        if (!registeredApp?.id && !canLaunchUnregisteredViewer) {
+            return buildFailedLoadCheckResult("app_registration_required_for_auth_validation", `Auth-required hosted app "${input.task.name}" must be registered on PlayDrop before viewer load-check can run. Run "playdrop project create app ${input.task.name}" and try again.`, null);
         }
-        const contextOptions = cloneLoadCheckContextOptions(captureSurface);
-        const anonymousExpectedState = resolveAnonymousHostedLaunchState({
-            ...localAppMetadata,
-            captureSurface,
+        const anonymousGateResult = await runHostedLoadCheck({
+            targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
+                creatorUsername: input.creatorUsername,
+                appName: input.task.name,
+                appType: input.task.type ?? "GAME",
+                devAuth: "anonymous",
+                launchCheck: true,
+                localDevPort,
+            }),
+            timeoutMs: input.timeoutMs,
+            expectedHostedLaunchState: anonymousExpectedState,
+            contextOptions,
+            installedChromeBrowser,
         });
-        if (input.captureSession) {
-            return await runHostedLoadCheck({
-                targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
-                    creatorUsername: input.creatorUsername,
-                    appName: input.task.name,
-                    appType: input.task.type ?? "GAME",
-                    devAuth: "player",
-                    player: "1",
-                    launchCheck: true,
-                    localDevPort,
-                    captureSession: input.captureSession,
-                }),
-                timeoutMs: input.timeoutMs,
-                expectedHostedLaunchState: resolvePostAuthHostedLaunchState(localAppMetadata.controllerMode),
-                contextOptions,
-                screenshotPath: input.screenshotPath,
-                playtestTape: input.playtestTape,
-                playtestSurface: captureSurface,
-                postReadyWaitMs: input.postReadyWaitMs,
-            });
-        }
-        if (anonymousExpectedState === "login_required") {
-            const registeredApp = await (0, registration_1.fetchRegisteredAppShell)(input.client, input.creatorUsername, input.task.name);
-            const canLaunchUnregisteredViewer = input.allowUnregisteredViewerLaunch === true && Boolean(input.token) && Boolean(input.currentUser);
-            if (!registeredApp?.id && !canLaunchUnregisteredViewer) {
-                return buildFailedLoadCheckResult("app_registration_required_for_auth_validation", `Auth-required hosted app "${input.task.name}" must be registered on PlayDrop before viewer load-check can run. Run "playdrop project create app ${input.task.name}" and try again.`, null);
-            }
-            const anonymousGateResult = await runHostedLoadCheck({
-                targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
-                    creatorUsername: input.creatorUsername,
-                    appName: input.task.name,
-                    appType: input.task.type ?? "GAME",
-                    devAuth: "anonymous",
-                    launchCheck: true,
-                    localDevPort,
-                }),
-                timeoutMs: input.timeoutMs,
-                expectedHostedLaunchState: anonymousExpectedState,
-                contextOptions,
-            });
-            if (anonymousGateResult.status !== "PASSED") {
-                return anonymousGateResult;
-            }
-            return await runHostedLoadCheck({
-                targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
-                    creatorUsername: input.creatorUsername,
-                    appName: input.task.name,
-                    appType: input.task.type ?? "GAME",
-                    devAuth: "player",
-                    player: "1",
-                    launchCheck: true,
-                    localDevPort,
-                }),
-                timeoutMs: input.timeoutMs,
-                expectedHostedLaunchState: resolvePostAuthHostedLaunchState(localAppMetadata.controllerMode),
-                token: input.token ?? null,
-                user: input.currentUser ?? null,
-                savedSessionBootstrap: true,
-                contextOptions,
-                screenshotPath: input.screenshotPath,
-                playtestTape: input.playtestTape,
-                playtestSurface: captureSurface,
-                postReadyWaitMs: input.postReadyWaitMs,
-            });
+        if (anonymousGateResult.status !== "PASSED") {
+            return anonymousGateResult;
         }
         return await runHostedLoadCheck({
             targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
                 creatorUsername: input.creatorUsername,
                 appName: input.task.name,
                 appType: input.task.type ?? "GAME",
-                devAuth: "anonymous",
+                devAuth: "player",
+                player: "1",
                 launchCheck: true,
                 localDevPort,
             }),
             timeoutMs: input.timeoutMs,
-            expectedHostedLaunchState: anonymousExpectedState,
+            expectedHostedLaunchState: resolvePostAuthHostedLaunchState(localAppMetadata.controllerMode),
+            token: input.token ?? null,
+            user: input.currentUser ?? null,
+            savedSessionBootstrap: true,
             contextOptions,
             screenshotPath: input.screenshotPath,
             playtestTape: input.playtestTape,
             playtestSurface: captureSurface,
             postReadyWaitMs: input.postReadyWaitMs,
+            installedChromeBrowser,
+        });
+    }
+    return await runHostedLoadCheck({
+        targetUrl: (0, appUrls_1.buildPlatformDevUrl)(input.webBase, {
+            creatorUsername: input.creatorUsername,
+            appName: input.task.name,
+            appType: input.task.type ?? "GAME",
+            devAuth: "anonymous",
+            launchCheck: true,
+            localDevPort,
+        }),
+        timeoutMs: input.timeoutMs,
+        expectedHostedLaunchState: anonymousExpectedState,
+        contextOptions,
+        screenshotPath: input.screenshotPath,
+        playtestTape: input.playtestTape,
+        playtestSurface: captureSurface,
+        postReadyWaitMs: input.postReadyWaitMs,
+        installedChromeBrowser,
+    });
+}
+async function mountLocalHostedLoadCheckRuntime(input) {
+    return await startOrReuseMountedDevRuntime({
+        client: input.client,
+        apiBase: input.apiBase,
+        creatorUsername: input.creatorUsername,
+        task: input.task,
+        devRouterPort: input.devRouterPort,
+        gameServerCredential: input.gameServerCredential,
+        gameServerBuild: input.gameServerBuild,
+    });
+}
+async function runLocalHostedLoadCheck(input) {
+    const mountedRuntime = await mountLocalHostedLoadCheckRuntime(input);
+    try {
+        return await runLocalHostedLoadCheckAgainstMountedRuntime(input, mountedRuntime);
+    }
+    finally {
+        if (mountedRuntime.handle)
+            await mountedRuntime.handle.close().catch(() => { });
+    }
+}
+async function runLocalHostedLoadCheckSequence(input) {
+    if (input.checks.length === 0) {
+        throw new Error("local_hosted_load_check_sequence_empty");
+    }
+    const { checks, ...baseInput } = input;
+    const mountStartedAt = Date.now();
+    const mountedRuntime = await mountLocalHostedLoadCheckRuntime(baseInput);
+    console.log(`[check] Local runtime ready in ${Date.now() - mountStartedAt} ms; reusing one mount for ${checks.length} gameplay passes.`);
+    try {
+        const chromeStartedAt = Date.now();
+        return await (0, playwright_1.withInstalledChromeBrowser)(async (installedChromeBrowser) => {
+            console.log(`[check] Chrome ready in ${Date.now() - chromeStartedAt} ms; reusing one process with isolated pages.`);
+            const results = [];
+            for (const check of checks) {
+                const result = await runLocalHostedLoadCheckAgainstMountedRuntime({ ...baseInput, ...check }, mountedRuntime, installedChromeBrowser);
+                results.push(result);
+                if (result.status !== "PASSED")
+                    break;
+            }
+            return results;
         });
     }
     finally {
-        if (mountedRuntime?.handle) {
+        if (mountedRuntime.handle)
             await mountedRuntime.handle.close().catch(() => { });
-        }
     }
 }
 function appendLoadCheckParams(targetUrl, devAuth) {
@@ -1214,6 +1252,7 @@ async function runUploadedHostedLoadCheck(input) {
             playtestSurface: captureSurface,
             postReadyWaitMs: input.postReadyWaitMs,
             verifyEditorPhaseRoundTrip: input.verifyEditorPhaseRoundTrip,
+            installedChromeBrowser: input.installedChromeBrowser,
         });
     }
     else if (anonymousExpectedState === "login_required") {
@@ -1229,6 +1268,7 @@ async function runUploadedHostedLoadCheck(input) {
                 contextOptions,
                 screenshotPath: input.screenshotPath,
                 failureScreenshotPath,
+                installedChromeBrowser: input.installedChromeBrowser,
             });
             if (anonymousGateResult.status !== "PASSED") {
                 result = anonymousGateResult;
@@ -1253,6 +1293,7 @@ async function runUploadedHostedLoadCheck(input) {
                     playtestSurface: captureSurface,
                     postReadyWaitMs: input.postReadyWaitMs,
                     verifyEditorPhaseRoundTrip: input.verifyEditorPhaseRoundTrip,
+                    installedChromeBrowser: input.installedChromeBrowser,
                 });
             }
         }
@@ -1272,6 +1313,7 @@ async function runUploadedHostedLoadCheck(input) {
             playtestSurface: captureSurface,
             postReadyWaitMs: input.postReadyWaitMs,
             verifyEditorPhaseRoundTrip: input.verifyEditorPhaseRoundTrip,
+            installedChromeBrowser: input.installedChromeBrowser,
         });
     }
     const recorded = await input.client.recordAppUploadLaunchCheck(input.creatorUsername, input.task.name, input.sessionId, {
@@ -1336,7 +1378,7 @@ async function runUploadedHostedPlaytestSmokeCheck(input) {
         zeroInput: (0, node_path_1.join)(tempDir, "zero-input.png"),
         fullTape: (0, node_path_1.join)(tempDir, "full-tape.png"),
     };
-    const run = async (label, options) => {
+    const run = async (installedChromeBrowser, label, options) => {
         console.log(`[upload] Playtest smoke check: ${label} from sdk.host.ready().`);
         const result = await runUploadedHostedLoadCheck({
             client: input.client,
@@ -1348,6 +1390,7 @@ async function runUploadedHostedPlaytestSmokeCheck(input) {
             token: input.token,
             currentUser: input.currentUser,
             captureSession: input.captureSession,
+            installedChromeBrowser,
             ...options,
         });
         if (result.status !== "PASSED") {
@@ -1360,43 +1403,47 @@ async function runUploadedHostedPlaytestSmokeCheck(input) {
         return result;
     };
     try {
-        const zeroInput = await run("zero-input", {
-            postReadyWaitMs: fullTape.durationMs,
-            gameFrameScreenshotPath: paths.zeroInput,
-        });
-        const full = await run("full-tape", {
-            playtestTape: fullTape,
-            gameFrameScreenshotPath: paths.fullTape,
+        const chromeStartedAt = Date.now();
+        return await (0, playwright_1.withInstalledChromeBrowser)(async (browser) => {
+            console.log(`[upload] Chrome ready in ${Date.now() - chromeStartedAt} ms; reusing one process with isolated pages.`);
+            const zeroInput = await run(browser, "zero-input", {
+                postReadyWaitMs: fullTape.durationMs,
+                gameFrameScreenshotPath: paths.zeroInput,
+            });
+            const full = await run(browser, "full-tape", {
+                playtestTape: fullTape,
+                gameFrameScreenshotPath: paths.fullTape,
+            });
+            const artifactFingerprint = full.artifactFingerprint;
+            if (zeroInput.artifactFingerprint !== artifactFingerprint) {
+                throw new Error("agent_task_playtest_smoke_check_artifact_changed_during_check");
+            }
+            const comparison = await comparePlaytestFrames(paths.zeroInput, paths.fullTape);
+            if (!comparison.passed) {
+                throw new Error(`agent_task_playtest_smoke_check_not_interactive: The validator completed all ${fullTape.events.length} tape actions ` +
+                    `without a crash, but the result looked the same as running the game for ${fullTape.durationMs} ms without input ` +
+                    `(mean pixel change ${comparison.meanDelta.toFixed(4)}, changed pixels ${(comparison.changedPixelRatio * 100).toFixed(2)}%). ` +
+                    "Make sure the tape performs the core gameplay action and produces a visible response, then rerun the tape check.");
+            }
+            const evidence = {
+                version: 2,
+                source: "CLI_MACHINE",
+                artifactFingerprint,
+                primarySurface,
+                primaryVerb: fullTape.primaryVerb,
+                runs: {
+                    zeroInput: { finalFrameSha256: await hashFile(paths.zeroInput) },
+                    fullTape: { finalFrameSha256: await hashFile(paths.fullTape) },
+                },
+                comparison,
+            };
+            const recorded = await input.client.recordAppUploadCausalCheck(input.creatorUsername, input.task.name, input.sessionId, { evidence });
+            if (recorded.session.causalCheck.status !== "PASSED") {
+                throw new Error("agent_task_playtest_smoke_check_not_recorded");
+            }
+            console.log(`[upload] Playtest smoke check passed for ${input.creatorUsername}/${input.task.name}.`);
+            return evidence;
         });
-        const artifactFingerprint = full.artifactFingerprint;
-        if (zeroInput.artifactFingerprint !== artifactFingerprint) {
-            throw new Error("agent_task_playtest_smoke_check_artifact_changed_during_check");
-        }
-        const comparison = await comparePlaytestFrames(paths.zeroInput, paths.fullTape);
-        if (!comparison.passed) {
-            throw new Error(`agent_task_playtest_smoke_check_not_interactive: The validator completed all ${fullTape.events.length} tape actions ` +
-                `without a crash, but the result looked the same as running the game for ${fullTape.durationMs} ms without input ` +
-                `(mean pixel change ${comparison.meanDelta.toFixed(4)}, changed pixels ${(comparison.changedPixelRatio * 100).toFixed(2)}%). ` +
-                "Make sure the tape performs the core gameplay action and produces a visible response, then rerun the tape check.");
-        }
-        const evidence = {
-            version: 2,
-            source: "CLI_MACHINE",
-            artifactFingerprint,
-            primarySurface,
-            primaryVerb: fullTape.primaryVerb,
-            runs: {
-                zeroInput: { finalFrameSha256: await hashFile(paths.zeroInput) },
-                fullTape: { finalFrameSha256: await hashFile(paths.fullTape) },
-            },
-            comparison,
-        };
-        const recorded = await input.client.recordAppUploadCausalCheck(input.creatorUsername, input.task.name, input.sessionId, { evidence });
-        if (recorded.session.causalCheck.status !== "PASSED") {
-            throw new Error("agent_task_playtest_smoke_check_not_recorded");
-        }
-        console.log(`[upload] Playtest smoke check passed for ${input.creatorUsername}/${input.task.name}.`);
-        return evidence;
     }
     finally {
         await (0, promises_1.rm)(tempDir, { recursive: true, force: true });

package/dist/commands/check.js

@@ -91,12 +91,13 @@ async function check(targetArg, options = {}) {
         process.exitCode = 1;
         return;
     }
+    let gameServerBuild = null;
     if (taskLookup.task.server) {
         try {
-            const serverBuild = await (0, serverBuild_1.buildGameServer)(taskLookup.task);
-            if (!serverBuild)
+            gameServerBuild = await (0, serverBuild_1.buildGameServer)(taskLookup.task);
+            if (!gameServerBuild)
                 throw new Error("server_build_missing");
-            console.log(`[check] Server contract passed: ${serverBuild.manifest.rooms.join(", ")} -> ${(0, serverBuild_1.formatServerBuildPath)(taskLookup.task, serverBuild.bundlePath)} (${serverBuild.manifest.size} bytes)`);
+            console.log(`[check] Server contract passed: ${gameServerBuild.manifest.rooms.join(", ")} -> ${(0, serverBuild_1.formatServerBuildPath)(taskLookup.task, gameServerBuild.bundlePath)} (${gameServerBuild.manifest.size} bytes)`);
         }
         catch (error) {
             (0, messages_1.printErrorWithHelp)(error instanceof Error ? error.message : "Server validation failed.", ["Fix the server declaration, frozen dependencies, imports, authentication, or bundle output."], { command: "project check" });
@@ -216,7 +217,7 @@ async function check(targetArg, options = {}) {
                 return;
             }
         }
-        const runCheck = async (input) => await (0, loadCheck_1.runLocalHostedLoadCheck)({
+        const localLoadCheckInput = {
             client,
             apiBase: envConfig.apiBase,
             webBase: envConfig.webBase,
@@ -227,30 +228,43 @@ async function check(targetArg, options = {}) {
             currentUser: null,
             devRouterPort: (0, dev_1.resolveCliDevRouterPort)(),
             captureSession,
+            gameServerCredential,
+            gameServerBuild,
+        };
+        const runCheck = async (input) => await (0, loadCheck_1.runLocalHostedLoadCheck)({
+            ...localLoadCheckInput,
             screenshotPath: input.screenshotPath,
             surface: input.surface,
             playtestTape: input.tape,
             postReadyWaitMs: input.postReadyWaitMs,
-            gameServerCredential,
         });
         if (tapeSurface && playtestTape) {
             const idleScreenshotPath = buildComparisonScreenshotPath(screenshotPath, "idle");
             const tapeScreenshotPath = buildComparisonScreenshotPath(screenshotPath, "tape");
-            const idleResult = await runCheck({
-                screenshotPath: idleScreenshotPath,
-                surface: tapeSurface,
-                postReadyWaitMs: playtestTape.durationMs,
+            const [idleResult, tapeResult] = await (0, loadCheck_1.runLocalHostedLoadCheckSequence)({
+                ...localLoadCheckInput,
+                checks: [
+                    {
+                        screenshotPath: idleScreenshotPath,
+                        surface: tapeSurface,
+                        postReadyWaitMs: playtestTape.durationMs,
+                    },
+                    {
+                        screenshotPath: tapeScreenshotPath,
+                        surface: tapeSurface,
+                        playtestTape,
+                    },
+                ],
             });
+            if (!idleResult)
+                throw new Error("local_playtest_idle_result_missing");
             if (idleResult.status !== "PASSED") {
                 (0, messages_1.printErrorWithHelp)((0, loadCheck_1.formatHostedLoadCheckFailure)(appName, idleResult, "local"), idleResult.screenshotPath ? [`Idle screenshot: ${idleResult.screenshotPath}`] : [], { command: "project check" });
                 process.exitCode = 1;
                 return;
             }
-            const tapeResult = await runCheck({
-                screenshotPath: tapeScreenshotPath,
-                surface: tapeSurface,
-                tape: playtestTape,
-            });
+            if (!tapeResult)
+                throw new Error("local_playtest_tape_result_missing");
             if (tapeResult.status !== "PASSED") {
                 (0, messages_1.printErrorWithHelp)((0, loadCheck_1.formatHostedLoadCheckFailure)(appName, tapeResult, "local"), tapeResult.screenshotPath ? [`Tape screenshot: ${tapeResult.screenshotPath}`] : [], { command: "project check" });
                 process.exitCode = 1;

package/dist/commands/creations.js

@@ -49,7 +49,7 @@ function parsePositiveInteger(raw, label, fallback) {
     }
     return parsed;
 }
-async function resolveCreator(client, rawCreator, command) {
+async function resolveCreator(client, rawCreator, command, workspaceCreatorUsername) {
     let creator;
     try {
         creator = (0, refs_1.parseCreatorOption)(rawCreator);
@@ -64,6 +64,10 @@ async function resolveCreator(client, rawCreator, command) {
     if (creator !== "me") {
         return creator;
     }
+    const workspaceCreator = workspaceCreatorUsername?.trim();
+    if (workspaceCreator) {
+        return workspaceCreator;
+    }
     const response = await client.me();
     const username = response.user?.username?.trim();
     if (!username) {
@@ -219,13 +223,14 @@ async function browseCreations(options = {}) {
         process.exitCode = 1;
         return;
     }
-    await (0, commandContext_1.withEnvironment)("creations browse", "Browsing your creations", async ({ client }) => {
+    await (0, commandContext_1.withEnvironment)("creations browse", "Browsing your creations", async ({ client, workspaceAuth }) => {
         try {
-            const creator = await resolveCreator(client, options.creator, "creations browse");
+            const workspaceCreator = workspaceAuth?.config.ownerUsername ?? null;
+            const creator = await resolveCreator(client, options.creator, "creations browse", workspaceCreator);
             if (!creator) {
                 return;
             }
-            const usingCurrentCreator = !options.creator || options.creator.trim().toLowerCase() === "me";
+            const usingCurrentCreator = !workspaceCreator && (!options.creator || options.creator.trim().toLowerCase() === "me");
             const items = [];
             let pagination;
             if (kind === "app") {

package/dist/commands/worker/archive-staging.d.ts

@@ -1,10 +1,17 @@
 type WorkspaceArchiveStageInput = {
-    downloadUrl: string;
+    downloadUrl?: string;
+    archivePath?: string;
     expectedSize: number;
     expectedSha256: string;
     targetDir: string;
     timeoutMs: number;
+    maxUncompressedBytes?: number;
 };
-export declare function extractZipArchive(zipBuffer: Uint8Array, targetDir: string): string[];
+export declare function extractZipArchive(zipBuffer: Uint8Array, targetDir: string, maxUncompressedBytes?: number): string[];
 export declare function stageWorkspaceArchiveInChild(input: WorkspaceArchiveStageInput): Promise<void>;
+export declare function stageZipArchiveBufferInChild(input: {
+    bytes: Uint8Array;
+    targetDir: string;
+    timeoutMs: number;
+}): Promise<void>;
 export {};

package/dist/commands/worker/archive-staging.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractZipArchive = extractZipArchive;
 exports.stageWorkspaceArchiveInChild = stageWorkspaceArchiveInChild;
+exports.stageZipArchiveBufferInChild = stageZipArchiveBufferInChild;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
@@ -17,7 +18,9 @@ const fflate_1 = require("fflate");
 const WORKSPACE_ARCHIVE_MAX_ENTRIES = 1000;
 const WORKSPACE_ARCHIVE_MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024;
 const WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES = 100 * 1024 * 1024;
+const ASSET_SOURCE_ARCHIVE_MAX_UNCOMPRESSED_BYTES = 256 * 1024 * 1024;
 const WORKSPACE_ARCHIVE_STAGER_MAX_OLD_SPACE_MB = 256;
+const ASSET_SOURCE_ARCHIVE_STAGER_MAX_OLD_SPACE_MB = 512;
 const WORKSPACE_ARCHIVE_STAGER_EXIT_GRACE_MS = 60000;
 const ZIP_CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
 const ZIP_END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50;
@@ -27,11 +30,15 @@ const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 function normalizeStageInput(value) {
     const input = value && typeof value === "object" && !Array.isArray(value) ? value : null;
     const downloadUrl = typeof input?.downloadUrl === "string" ? input.downloadUrl.trim() : "";
+    const archivePath = typeof input?.archivePath === "string" ? input.archivePath.trim() : "";
     const expectedSize = Number(input?.expectedSize);
     const expectedSha256 = typeof input?.expectedSha256 === "string" ? input.expectedSha256.trim().toLowerCase() : "";
     const targetDir = typeof input?.targetDir === "string" ? input.targetDir.trim() : "";
     const timeoutMs = Number(input?.timeoutMs);
-    if (!downloadUrl ||
+    const maxUncompressedBytes = input?.maxUncompressedBytes == null
+        ? WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES
+        : Number(input.maxUncompressedBytes);
+    if (Boolean(downloadUrl) === Boolean(archivePath) ||
         !Number.isInteger(expectedSize) ||
         expectedSize <= 0 ||
         !/^[0-9a-f]{64}$/.test(expectedSha256) ||
@@ -44,9 +51,24 @@ function normalizeStageInput(value) {
     if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
         throw new Error("agent_task_workspace_archive_download_timeout_invalid");
     }
-    return { downloadUrl, expectedSize, expectedSha256, targetDir, timeoutMs };
+    if (maxUncompressedBytes !== WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES &&
+        maxUncompressedBytes !== ASSET_SOURCE_ARCHIVE_MAX_UNCOMPRESSED_BYTES) {
+        throw new Error("agent_task_workspace_archive_uncompressed_limit_invalid");
+    }
+    if (archivePath && !node_path_1.default.isAbsolute(archivePath)) {
+        throw new Error("agent_task_workspace_archive_stager_input_invalid");
+    }
+    return {
+        ...(downloadUrl ? { downloadUrl } : {}),
+        ...(archivePath ? { archivePath } : {}),
+        expectedSize,
+        expectedSha256,
+        targetDir,
+        timeoutMs,
+        maxUncompressedBytes,
+    };
 }
-function assertWorkspaceArchiveExtractionBounds(buffer) {
+function assertWorkspaceArchiveExtractionBounds(buffer, maxUncompressedBytes) {
     if (buffer.length < ZIP_END_OF_CENTRAL_DIRECTORY_MIN_BYTES) {
         throw new Error("agent_task_workspace_archive_invalid_zip");
     }
@@ -104,8 +126,8 @@ function assertWorkspaceArchiveExtractionBounds(buffer) {
             throw new Error("agent_task_workspace_archive_invalid_zip");
         }
         uncompressedBytes += uncompressedSize;
-        if (uncompressedBytes > WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES) {
-            throw new Error(`agent_task_workspace_archive_too_large:${uncompressedBytes}>${WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES}`);
+        if (uncompressedBytes > maxUncompressedBytes) {
+            throw new Error(`agent_task_workspace_archive_too_large:${uncompressedBytes}>${maxUncompressedBytes}`);
         }
         cursor = nextCursor;
     }
@@ -116,8 +138,8 @@ function assertWorkspaceArchiveExtractionBounds(buffer) {
 // This synchronous work is intentionally executed only by the disposable archive
 // child. A malformed ZIP can terminate that child without blocking or terminating
 // the long-lived worker process that owns presence and task heartbeats.
-function extractZipArchive(zipBuffer, targetDir) {
-    assertWorkspaceArchiveExtractionBounds(Buffer.from(zipBuffer.buffer, zipBuffer.byteOffset, zipBuffer.byteLength));
+function extractZipArchive(zipBuffer, targetDir, maxUncompressedBytes = WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES) {
+    assertWorkspaceArchiveExtractionBounds(Buffer.from(zipBuffer.buffer, zipBuffer.byteOffset, zipBuffer.byteLength), maxUncompressedBytes);
     const files = (0, fflate_1.unzipSync)(zipBuffer);
     const names = Object.keys(files);
     if (names.length === 0) {
@@ -143,8 +165,8 @@ function extractZipArchive(zipBuffer, targetDir) {
             continue;
         }
         uncompressedBytes += files[originalName].byteLength;
-        if (uncompressedBytes > WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES) {
-            throw new Error(`agent_task_workspace_archive_too_large:${uncompressedBytes}>${WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES}`);
+        if (uncompressedBytes > maxUncompressedBytes) {
+            throw new Error(`agent_task_workspace_archive_too_large:${uncompressedBytes}>${maxUncompressedBytes}`);
         }
         (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(destination), { recursive: true });
         (0, node_fs_1.writeFileSync)(destination, Buffer.from(files[originalName]));
@@ -159,55 +181,65 @@ async function downloadAndExtractWorkspaceArchive(input) {
     const archivePath = node_path_1.default.join(stagingRoot, "archive.zip");
     const extractedDir = node_path_1.default.join(stagingRoot, "contents");
     try {
-        const response = await fetch(input.downloadUrl, { signal: controller.signal });
-        if (!response.ok) {
-            throw new Error(`agent_task_workspace_archive_http_error:${response.status}`);
-        }
-        const contentLength = response.headers.get("content-length");
-        if (contentLength !== null && Number(contentLength) !== input.expectedSize) {
-            throw new Error(`agent_task_workspace_archive_size_mismatch:${contentLength}!=${input.expectedSize}`);
-        }
-        if (!response.body) {
-            throw new Error("agent_task_workspace_archive_body_missing");
-        }
-        const reader = response.body.getReader();
-        const file = await (0, promises_1.open)(archivePath, "wx");
-        const hash = (0, node_crypto_1.createHash)("sha256");
         let receivedBytes = 0;
-        try {
-            while (true) {
-                const chunk = await reader.read();
-                if (chunk.done) {
-                    break;
-                }
-                const buffer = Buffer.from(chunk.value);
-                hash.update(buffer);
-                if (receivedBytes + buffer.length > input.expectedSize) {
-                    throw new Error(`agent_task_workspace_archive_size_mismatch:${receivedBytes + buffer.length}>${input.expectedSize}`);
-                }
-                let chunkOffset = 0;
-                while (chunkOffset < buffer.length) {
-                    const result = await file.write(buffer, chunkOffset, buffer.length - chunkOffset, receivedBytes + chunkOffset);
-                    if (result.bytesWritten <= 0) {
-                        throw new Error("agent_task_workspace_archive_write_failed");
+        let receivedSha256 = "";
+        if (input.archivePath) {
+            const source = await (0, promises_1.readFile)(input.archivePath);
+            receivedBytes = source.length;
+            receivedSha256 = (0, node_crypto_1.createHash)("sha256").update(source).digest("hex");
+            await (0, promises_1.writeFile)(archivePath, source, { flag: "wx" });
+        }
+        else {
+            const response = await fetch(input.downloadUrl, { signal: controller.signal });
+            if (!response.ok) {
+                throw new Error(`agent_task_workspace_archive_http_error:${response.status}`);
+            }
+            const contentLength = response.headers.get("content-length");
+            if (contentLength !== null && Number(contentLength) !== input.expectedSize) {
+                throw new Error(`agent_task_workspace_archive_size_mismatch:${contentLength}!=${input.expectedSize}`);
+            }
+            if (!response.body) {
+                throw new Error("agent_task_workspace_archive_body_missing");
+            }
+            const reader = response.body.getReader();
+            const file = await (0, promises_1.open)(archivePath, "wx");
+            const hash = (0, node_crypto_1.createHash)("sha256");
+            try {
+                while (true) {
+                    const chunk = await reader.read();
+                    if (chunk.done) {
+                        break;
+                    }
+                    const buffer = Buffer.from(chunk.value);
+                    hash.update(buffer);
+                    if (receivedBytes + buffer.length > input.expectedSize) {
+                        throw new Error(`agent_task_workspace_archive_size_mismatch:${receivedBytes + buffer.length}>${input.expectedSize}`);
                     }
-                    chunkOffset += result.bytesWritten;
+                    let chunkOffset = 0;
+                    while (chunkOffset < buffer.length) {
+                        const result = await file.write(buffer, chunkOffset, buffer.length - chunkOffset, receivedBytes + chunkOffset);
+                        if (result.bytesWritten <= 0) {
+                            throw new Error("agent_task_workspace_archive_write_failed");
+                        }
+                        chunkOffset += result.bytesWritten;
+                    }
+                    receivedBytes += buffer.length;
                 }
-                receivedBytes += buffer.length;
             }
-        }
-        finally {
-            await file.close();
+            finally {
+                await file.close();
+            }
+            receivedSha256 = hash.digest("hex");
         }
         if (receivedBytes !== input.expectedSize) {
             throw new Error(`agent_task_workspace_archive_size_mismatch:${receivedBytes}!=${input.expectedSize}`);
         }
-        if (hash.digest("hex") !== input.expectedSha256) {
+        if (receivedSha256 !== input.expectedSha256) {
             throw new Error("agent_task_workspace_archive_sha_mismatch");
         }
         const buffer = await (0, promises_1.readFile)(archivePath);
         await (0, promises_1.mkdir)(extractedDir, { recursive: true });
-        extractZipArchive(new Uint8Array(buffer), extractedDir);
+        extractZipArchive(new Uint8Array(buffer), extractedDir, input.maxUncompressedBytes);
         await (0, promises_1.mkdir)(node_path_1.default.dirname(input.targetDir), { recursive: true });
         await (0, promises_1.rm)(input.targetDir, { recursive: true, force: true });
         await (0, promises_1.rename)(extractedDir, input.targetDir);
@@ -239,9 +271,15 @@ function childFailureDetail(error) {
 }
 async function stageWorkspaceArchiveInChild(input) {
     const normalized = normalizeStageInput(input);
+    await runArchiveStagerProcess(normalized);
+}
+async function runArchiveStagerProcess(normalized) {
+    const maxOldSpaceMb = normalized.maxUncompressedBytes === ASSET_SOURCE_ARCHIVE_MAX_UNCOMPRESSED_BYTES
+        ? ASSET_SOURCE_ARCHIVE_STAGER_MAX_OLD_SPACE_MB
+        : WORKSPACE_ARCHIVE_STAGER_MAX_OLD_SPACE_MB;
     try {
         await execFileAsync(node_process_1.default.execPath, [
-            `--max-old-space-size=${WORKSPACE_ARCHIVE_STAGER_MAX_OLD_SPACE_MB}`,
+            `--max-old-space-size=${maxOldSpaceMb}`,
             __filename,
             JSON.stringify(normalized),
         ], {
@@ -253,6 +291,29 @@ async function stageWorkspaceArchiveInChild(input) {
         throw new Error(`agent_task_workspace_archive_stager_failed:${childFailureDetail(error)}`);
     }
 }
+async function stageZipArchiveBufferInChild(input) {
+    const bytes = Buffer.from(input.bytes.buffer, input.bytes.byteOffset, input.bytes.byteLength);
+    if (bytes.length <= 0 || bytes.length > WORKSPACE_ARCHIVE_MAX_DOWNLOAD_BYTES) {
+        throw new Error(`agent_task_workspace_archive_download_too_large:${bytes.length}>${WORKSPACE_ARCHIVE_MAX_DOWNLOAD_BYTES}`);
+    }
+    const stagingRoot = await (0, promises_1.mkdtemp)(node_path_1.default.join(node_os_1.default.tmpdir(), "playdrop-local-workspace-archive-"));
+    const archivePath = node_path_1.default.join(stagingRoot, "archive.zip");
+    try {
+        await (0, promises_1.writeFile)(archivePath, bytes, { flag: "wx" });
+        const normalized = normalizeStageInput({
+            archivePath,
+            expectedSize: bytes.length,
+            expectedSha256: (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex"),
+            targetDir: input.targetDir,
+            timeoutMs: input.timeoutMs,
+            maxUncompressedBytes: ASSET_SOURCE_ARCHIVE_MAX_UNCOMPRESSED_BYTES,
+        });
+        await runArchiveStagerProcess(normalized);
+    }
+    finally {
+        await (0, promises_1.rm)(stagingRoot, { recursive: true, force: true });
+    }
+}
 async function runArchiveStagerChild() {
     const rawInput = node_process_1.default.argv[2];
     if (!rawInput) {

package/dist/commands/worker.d.ts

@@ -292,6 +292,12 @@ export declare function assertTaskUploadResultMatchesContext(input: {
 export declare function stageAssignmentWorkspace(workspaceDir: string, workspace: WorkerGameTaskAssignment["workspace"], options?: {
     timeoutMs?: number;
 }): Promise<void>;
+export declare function stageReferencedAssetInputs(input: {
+    workspaceDir: string;
+    taskContext: Omit<WorkerTaskContextFile, "env" | "devPort">;
+    client: Pick<ApiClient, "downloadAssetSource">;
+    timeoutMs?: number;
+}): Promise<Omit<WorkerTaskContextFile, "env" | "devPort">>;
 export declare function assertAssignmentPluginBundleExtractionBounds(buffer: Buffer): void;
 export declare function stageDevPluginWorkingTree(input: {
     workingTree: string;

package/dist/commands/worker.js

@@ -38,6 +38,7 @@ exports.readTaskUploadResultFile = readTaskUploadResultFile;
 exports.readTaskNextStepsFile = readTaskNextStepsFile;
 exports.assertTaskUploadResultMatchesContext = assertTaskUploadResultMatchesContext;
 exports.stageAssignmentWorkspace = stageAssignmentWorkspace;
+exports.stageReferencedAssetInputs = stageReferencedAssetInputs;
 exports.assertAssignmentPluginBundleExtractionBounds = assertAssignmentPluginBundleExtractionBounds;
 exports.stageDevPluginWorkingTree = stageDevPluginWorkingTree;
 exports.stageAssignmentPluginBundle = stageAssignmentPluginBundle;
@@ -320,6 +321,7 @@ const WORKER_CONTEXT_ALLOWED_COMMANDS = [
     ["project", "check"],
     ["project", "capture"],
     ["browse"],
+    ["creations", "browse"],
     ["search"],
     ["detail"],
     ["app", "source"],
@@ -1802,6 +1804,170 @@ async function stageAssignmentWorkspace(workspaceDir, workspace, options = {}) {
         await removeStaleWorkerControlFiles(destination);
     }
 }
+function normalizeReferenceAssetRevision(value, inputId) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    const match = /^r?([1-9]\d*)$/i.exec(raw);
+    const revision = match?.[1] ? Number.parseInt(match[1], 10) : Number.NaN;
+    if (!Number.isSafeInteger(revision) || revision <= 0) {
+        throw new Error(`agent_task_reference_asset_version_missing:${inputId}`);
+    }
+    return revision;
+}
+function resolveReferenceAssetInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entry = value;
+    if (entry.kind !== "REFERENCE_ASSET")
+        return null;
+    const id = typeof entry.id === "string" ? entry.id.trim() : "";
+    if (!id || !/^[a-zA-Z0-9_-]+$/.test(id)) {
+        throw new Error("agent_task_reference_asset_input_id_invalid");
+    }
+    const referenceValue = entry.reference;
+    if (!referenceValue || typeof referenceValue !== "object" || Array.isArray(referenceValue)) {
+        throw new Error(`agent_task_reference_asset_invalid:${id}`);
+    }
+    const reference = referenceValue;
+    const rawRef = typeof reference.ref === "string" ? reference.ref.trim() : "";
+    const parsed = rawRef ? (0, types_1.parseContentVersionRef)(rawRef) : null;
+    const legacyMatch = /^playdrop:\/\/assets\/([^/?#]+)\/([^/?#]+)$/.exec(rawRef);
+    if ((parsed && parsed.kind !== "asset") || (!parsed && !legacyMatch)) {
+        throw new Error(`agent_task_reference_asset_invalid:${id}`);
+    }
+    let creatorUsername;
+    let name;
+    let revision;
+    if (parsed?.kind === "asset") {
+        creatorUsername = parsed.creatorUsername;
+        name = parsed.name;
+        revision = parsed.revision;
+        const declaredCreator = typeof reference.creatorUsername === "string" ? reference.creatorUsername.trim() : "";
+        const declaredName = typeof reference.name === "string" ? reference.name.trim() : "";
+        if ((declaredCreator && declaredCreator !== creatorUsername) || (declaredName && declaredName !== name)) {
+            throw new Error(`agent_task_reference_asset_mismatch:${id}`);
+        }
+        if (reference.version != null && normalizeReferenceAssetRevision(reference.version, id) !== revision) {
+            throw new Error(`agent_task_reference_asset_mismatch:${id}`);
+        }
+    }
+    else {
+        creatorUsername = typeof reference.creatorUsername === "string" ? reference.creatorUsername.trim() : "";
+        name = typeof reference.name === "string" ? reference.name.trim() : "";
+        if (!creatorUsername || !name) {
+            throw new Error(`agent_task_reference_asset_invalid:${id}`);
+        }
+        if (legacyMatch?.[1] !== creatorUsername || legacyMatch[2] !== name) {
+            throw new Error(`agent_task_reference_asset_mismatch:${id}`);
+        }
+        revision = normalizeReferenceAssetRevision(reference.version, id);
+    }
+    const ref = `asset:${creatorUsername}/${name}@r${revision}`;
+    return {
+        id,
+        ref,
+        creatorUsername,
+        name,
+        revision,
+        workspacePath: `inputs/assets/${id}`,
+    };
+}
+async function stageReferencedAssetInputs(input) {
+    const playdropValue = input.taskContext.metadata.playdrop;
+    if (!playdropValue || typeof playdropValue !== "object" || Array.isArray(playdropValue)) {
+        throw new Error("agent_task_context_playdrop_metadata_missing");
+    }
+    const playdrop = playdropValue;
+    const rawInputs = playdrop.inputs;
+    if (rawInputs == null)
+        return input.taskContext;
+    if (!Array.isArray(rawInputs)) {
+        throw new Error("agent_task_reference_asset_inputs_invalid");
+    }
+    const resolvedById = new Map();
+    for (const value of rawInputs) {
+        const resolved = resolveReferenceAssetInput(value);
+        if (!resolved)
+            continue;
+        if (resolvedById.has(resolved.id)) {
+            throw new Error(`agent_task_reference_asset_input_duplicate:${resolved.id}`);
+        }
+        resolvedById.set(resolved.id, resolved);
+        try {
+            const source = await input.client.downloadAssetSource(resolved.creatorUsername, resolved.name, resolved.revision);
+            const bytes = new Uint8Array(await source.blob.arrayBuffer());
+            if (bytes.length !== source.metadata.sizeBytes) {
+                throw new Error(`source_download_incomplete:expected_${source.metadata.sizeBytes}_received_${bytes.length}`);
+            }
+            await (0, archive_staging_1.stageZipArchiveBufferInChild)({
+                bytes,
+                targetDir: resolveWorkspaceFileDestination(input.workspaceDir, resolved.workspacePath),
+                timeoutMs: input.timeoutMs ?? exports.WORKSPACE_ARCHIVE_DOWNLOAD_TIMEOUT_MS,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`agent_task_reference_asset_stage_failed:${resolved.id}:${detail}`);
+        }
+    }
+    if (resolvedById.size === 0)
+        return input.taskContext;
+    const localizedInputs = rawInputs.map((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return value;
+        const entry = value;
+        const id = typeof entry.id === "string" ? entry.id.trim() : "";
+        const resolved = resolvedById.get(id);
+        if (!resolved)
+            return value;
+        const reference = entry.reference;
+        return {
+            ...entry,
+            workspacePath: resolved.workspacePath,
+            reference: {
+                ...reference,
+                ref: resolved.ref,
+                creatorUsername: resolved.creatorUsername,
+                name: resolved.name,
+                version: `r${resolved.revision}`,
+            },
+        };
+    });
+    return {
+        ...input.taskContext,
+        metadata: {
+            ...input.taskContext.metadata,
+            playdrop: {
+                ...playdrop,
+                inputs: localizedInputs,
+            },
+        },
+    };
+}
+function buildStagedReferenceAssetPrompt(taskContext) {
+    const playdropValue = taskContext.metadata.playdrop;
+    if (!playdropValue || typeof playdropValue !== "object" || Array.isArray(playdropValue))
+        return null;
+    const inputs = playdropValue.inputs;
+    if (!Array.isArray(inputs))
+        return null;
+    const staged = inputs.flatMap((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return [];
+        const entry = value;
+        if (entry.kind !== "REFERENCE_ASSET" || typeof entry.workspacePath !== "string")
+            return [];
+        const reference = entry.reference;
+        if (!reference || typeof reference !== "object" || Array.isArray(reference))
+            return [];
+        const ref = reference.ref;
+        if (typeof ref !== "string")
+            return [];
+        return [`- ${ref}: ${entry.workspacePath}`];
+    });
+    if (staged.length === 0)
+        return null;
+    return ["Attached PlayDrop assets are already available in the workspace:", ...staged].join("\n");
+}
 function isFile(candidatePath) {
     try {
         return (0, node_fs_1.statSync)(candidatePath).isFile();
@@ -5608,7 +5774,7 @@ async function startWorker(options = {}) {
                 });
             }, HEARTBEAT_INTERVAL_MS);
             const runClaimedTask = async (assignment, leaseToken, devPort) => {
-                const taskContext = buildWorkerTaskContextV2(assignment);
+                let taskContext = buildWorkerTaskContextV2(assignment);
                 const task = {
                     id: assignment.task.id,
                     kind: taskContext.kind,
@@ -6165,14 +6331,6 @@ async function startWorker(options = {}) {
                             createdAt: new Date().toISOString(),
                         })}\n`, "utf8");
                     }
-                    if (!cleanRoom || assignment.gameSource) {
-                        await stageWorkerTaskContext({
-                            workspaceDir,
-                            env,
-                            devPort,
-                            taskContext,
-                        });
-                    }
                     const binDir = cleanRoom
                         ? await createStaticGameCleanToolPath(workspaceDir, assignment.agent.runtime)
                         : await createLocalPlaydropShim({
@@ -6231,6 +6389,27 @@ async function startWorker(options = {}) {
                         }
                     };
                     await stageAssignmentWorkspace(agentWorkspaceDir, assignment.workspace);
+                    const referenceAssetClient = (0, apiClient_1.createCliApiClient)({
+                        baseUrl: envConfig.apiBase,
+                        token: taskContext.taskAccessToken?.trim() || ctx.getToken(),
+                        onBehalfCreatorUsername: taskContext.creatorUsername,
+                        agentTaskToken: assignment.task.token,
+                        agentTaskId: task.id,
+                        agentTaskAttempt: taskContext.attempt,
+                    });
+                    taskContext = await stageReferencedAssetInputs({
+                        workspaceDir: agentWorkspaceDir,
+                        taskContext,
+                        client: referenceAssetClient,
+                    });
+                    if (!cleanRoom || assignment.gameSource) {
+                        await stageWorkerTaskContext({
+                            workspaceDir,
+                            env,
+                            devPort,
+                            taskContext,
+                        });
+                    }
                     if (fenced) {
                         throw new Error("agent_task_lease_invalid");
                     }
@@ -6348,7 +6527,8 @@ async function startWorker(options = {}) {
                         : task.kind === "GAME_EVAL" && preparedWorkspace.resumed
                             ? buildGameEvalRetryPrompt(assignment.request.prompt)
                             : assignment.request.prompt;
-                    const prompt = basePrompt;
+                    const stagedAssetPrompt = buildStagedReferenceAssetPrompt(taskContext);
+                    const prompt = stagedAssetPrompt ? `${basePrompt}\n\n${stagedAssetPrompt}` : basePrompt;
                     const imageAttachments = assignment.request.attachments
                         .filter((attachment) => attachment.contentType.startsWith("image/"))
                         .map((attachment) => ({

package/dist/playwright.d.ts

@@ -25,6 +25,7 @@ type PlaydropBrowserContextOptions = BrowserContextOptions & {
 export declare function setPlaywrightLoader(loader: (() => Promise<PlaywrightModule>) | null): void;
 export declare function createPlaywrightLaunchError(tool: string, error: unknown): Error;
 export declare function createInstalledChromeLaunchError(tool: string, error: unknown): Error;
+type BrowserCallback<T> = (browser: Browser) => Promise<T>;
 type PageCallback<T> = (context: {
     browser: Browser;
     context: BrowserContext;
@@ -33,6 +34,7 @@ type PageCallback<T> = (context: {
 export declare function withChromiumPage<T>(callback: PageCallback<T>, options?: PlaydropBrowserContextOptions): Promise<T>;
 /** Procedural publication must exercise normal browser CORS and CSP enforcement. */
 export declare function withBrowserValidationPage<T>(callback: PageCallback<T>, options?: PlaydropBrowserContextOptions): Promise<T>;
-export declare function withInstalledChromePage<T>(callback: PageCallback<T>, options?: PlaydropBrowserContextOptions): Promise<T>;
+export declare function withInstalledChromePage<T>(callback: PageCallback<T>, options?: PlaydropBrowserContextOptions, existingBrowser?: Browser): Promise<T>;
+export declare function withInstalledChromeBrowser<T>(callback: BrowserCallback<T>): Promise<T>;
 export declare function launchPersistentChromiumContext(userDataDir: string, options?: PlaydropBrowserContextOptions): Promise<BrowserContext>;
 export {};

package/dist/playwright.js

@@ -40,6 +40,7 @@ exports.createInstalledChromeLaunchError = createInstalledChromeLaunchError;
 exports.withChromiumPage = withChromiumPage;
 exports.withBrowserValidationPage = withBrowserValidationPage;
 exports.withInstalledChromePage = withInstalledChromePage;
+exports.withInstalledChromeBrowser = withInstalledChromeBrowser;
 exports.launchPersistentChromiumContext = launchPersistentChromiumContext;
 const node_url_1 = require("node:url");
 const TOOL_NAME = "playdrop";
@@ -170,7 +171,13 @@ async function withHeadlessChromiumPage(callback, options, args) {
         }
     }
 }
-async function withInstalledChromePage(callback, options = {}) {
+async function withInstalledChromePage(callback, options = {}, existingBrowser) {
+    if (existingBrowser) {
+        return await withPageInBrowser(existingBrowser, callback, options);
+    }
+    return await withInstalledChromeBrowser(async (browser) => await withPageInBrowser(browser, callback, options));
+}
+async function withInstalledChromeBrowser(callback) {
     const { chromium } = await loadPlaywright();
     let browser;
     try {
@@ -184,6 +191,20 @@ async function withInstalledChromePage(callback, options = {}) {
     catch (error) {
         throw createInstalledChromeLaunchError(TOOL_NAME, error);
     }
+    try {
+        return await callback(browser);
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch (closeError) {
+            const message = closeError instanceof Error ? closeError.message : String(closeError);
+            console.warn(`[${TOOL_NAME}] Failed to close Playwright browser: ${message}`);
+        }
+    }
+}
+async function withPageInBrowser(browser, callback, options) {
     let context = null;
     try {
         const { automationOrigin, ...contextOptions } = options;
@@ -202,13 +223,6 @@ async function withInstalledChromePage(callback, options = {}) {
                 console.warn(`[${TOOL_NAME}] Failed to close Playwright context: ${message}`);
             }
         }
-        try {
-            await browser.close();
-        }
-        catch (closeError) {
-            const message = closeError instanceof Error ? closeError.message : String(closeError);
-            console.warn(`[${TOOL_NAME}] Failed to close Playwright browser: ${message}`);
-        }
     }
 }
 async function launchPersistentChromiumContext(userDataDir, options = {}) {

package/node_modules/@playdrop/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.17.19",
+  "version": "0.17.21",
   "build": 1,
-  "runtimeSdkVersion": "0.17.19",
+  "runtimeSdkVersion": "0.17.21",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playdrop/playdrop-cli",
-  "version": "0.17.19",
+  "version": "0.17.21",
   "description": "Official Playdrop CLI for publishing browser games, creator apps, and AI-generated game assets on playdrop.ai",
   "homepage": "https://www.playdrop.ai",
   "repository": {