@playdrop/playdrop-cli 0.10.18 → 0.10.20

package/config/client-meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.18",
+  "version": "0.10.20",
   "build": 1,
   "runtimeSdkVersion": "0.10.0",
   "clients": {

package/dist/apps/index.js

@@ -19,8 +19,8 @@ async function runAppPipeline(client, task, options) {
     await (0, validate_1.validateAppTask)(task);
     // External apps don't need to be built - they're hosted elsewhere
     const isExternal = task.hostingMode === 'EXTERNAL' || !!task.externalUrl;
-    const requiresRegisteredShell = !isExternal && task.authMode === 'REQUIRED';
-    if (requiresRegisteredShell && options?.ensureRegisteredAppShell) {
+    const shouldEnsureRegisteredShell = !isExternal && options?.ensureRegisteredAppShell;
+    if (shouldEnsureRegisteredShell) {
         const creatorUsername = typeof options.creatorUsername === 'string' ? options.creatorUsername.trim() : '';
         if (!creatorUsername) {
             throw new Error(`Missing creator username for required hosted app registration of "${task.name}".`);

package/dist/apps/registration.js

@@ -28,6 +28,7 @@ async function ensureRegisteredHostedAppShell(input) {
             name: input.task.name,
             displayName,
             ...(input.agentTaskId !== undefined ? { agentTaskId: input.agentTaskId } : {}),
+            ...(input.task.remix ? { remixRef: input.task.remix } : {}),
         });
         app = createdResponse.app;
         created = true;

package/dist/captureRuntime.d.ts

@@ -13,6 +13,7 @@ export type RunCaptureOptions = {
     expectedUrl?: string | null;
     timeoutMs: number;
     settleAfterReadyMs?: number;
+    frameRateSampleMs?: number;
     minimumLogLevel: CaptureLogLevel;
     screenshotPath?: string | null;
     logPath?: string | null;
@@ -59,6 +60,12 @@ export type CaptureRunResult = {
     warnings: string[];
     finalUrl: string;
     hostedLaunchState: CaptureHostedLaunchState | null;
+    frameRate: CaptureFrameRateSample | null;
+};
+export type CaptureFrameRateSample = {
+    fps: number;
+    sampleMs: number;
+    frameCount: number;
 };
 export declare function resolveCaptureLogLevel(value: string | undefined): CaptureLogLevel;
 export declare function validateCaptureTimeout(value: number | undefined): number;

package/dist/captureRuntime.js

@@ -526,6 +526,36 @@ async function runCaptureActions(page, actions) {
         throw new Error('capture_action_type_unknown');
     }
 }
+async function sampleFrameRate(page, sampleMs) {
+    if (!Number.isInteger(sampleMs) || sampleMs <= 0) {
+        throw new Error('capture_fps_sample_invalid');
+    }
+    const childFrames = page.frames().filter(frame => frame.parentFrame() !== null);
+    const target = childFrames[0] ?? page;
+    const sample = await target.evaluate((durationMs) => new Promise((resolve) => {
+        const startedAt = performance.now();
+        let frameCount = 0;
+        const tick = (timestamp) => {
+            frameCount += 1;
+            const elapsedMs = Math.max(timestamp - startedAt, 0);
+            if (elapsedMs >= durationMs) {
+                resolve({
+                    fps: frameCount > 0 && elapsedMs > 0 ? frameCount * 1000 / elapsedMs : 0,
+                    sampleMs: elapsedMs,
+                    frameCount,
+                });
+                return;
+            }
+            requestAnimationFrame(tick);
+        };
+        requestAnimationFrame(tick);
+    }), sampleMs);
+    return {
+        fps: Number(sample.fps.toFixed(2)),
+        sampleMs: Math.round(sample.sampleMs),
+        frameCount: sample.frameCount,
+    };
+}
 async function assertHostedFrameVisualReadiness(page) {
     const childFrames = page.frames().filter(frame => frame.parentFrame() !== null);
     if (childFrames.length === 0) {
@@ -596,6 +626,7 @@ async function runCapture(options) {
     const bootstrapUser = shouldBootstrapSavedSession ? options.user ?? null : null;
     let finalUrl = options.targetUrl;
     let hostedLaunchState = null;
+    let frameRate = null;
     const record = (level, message) => {
         const line = `[capture][${level}] ${message}`;
         outputLines.push(line);
@@ -959,6 +990,10 @@ async function runCapture(options) {
                 await page.screenshot({ path: options.screenshotPath, fullPage: true });
                 console.log(`[capture] Saved screenshot to ${(0, node_path_1.relative)(process.cwd(), options.screenshotPath) || options.screenshotPath}`);
             }
+            if (options.frameRateSampleMs && options.frameRateSampleMs > 0) {
+                frameRate = await sampleFrameRate(page, options.frameRateSampleMs);
+                record('info', `Frame-rate sample: ${frameRate.fps.toFixed(2)} fps over ${frameRate.sampleMs}ms (${frameRate.frameCount} frames).`);
+            }
         }, {
             ...(options.contextOptions ?? {}),
             automationOrigin: resolveAutomationOrigin(options.targetUrl),
@@ -974,5 +1009,6 @@ async function runCapture(options) {
         warnings,
         finalUrl,
         hostedLaunchState,
+        frameRate,
     };
 }

package/dist/commands/captureRemote.d.ts

@@ -1,5 +1,6 @@
 type CaptureRemoteOptions = {
     timeout?: string | number;
+    settle?: string | number;
     screenshot?: string;
     log?: string;
     expectedUrl?: string;
@@ -8,6 +9,7 @@ type CaptureRemoteOptions = {
     loginUrl?: string;
     actions?: string;
     viewport?: string;
+    fpsSampleMs?: string | number;
 };
 export declare function buildCaptureRemoteCommandArgs(url: string | undefined, options?: CaptureRemoteOptions): string[] | null;
 export declare function captureRemote(url: string | undefined, options?: CaptureRemoteOptions): Promise<void>;

package/dist/commands/captureRemote.js

@@ -43,6 +43,16 @@ function parseTimeout(raw) {
     }
     return parsed;
 }
+function parseSettle(raw) {
+    if (raw === undefined) {
+        return 1;
+    }
+    const parsed = typeof raw === 'number' ? raw : Number.parseFloat(String(raw));
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 600) {
+        throw new Error('invalid_settle');
+    }
+    return parsed;
+}
 function parseViewport(raw) {
     const value = raw?.trim();
     if (!value) {
@@ -59,6 +69,16 @@ function parseViewport(raw) {
     }
     return { width, height };
 }
+function parseFpsSampleMs(raw) {
+    if (raw === undefined) {
+        return null;
+    }
+    const parsed = typeof raw === 'number' ? raw : Number.parseFloat(String(raw));
+    if (!Number.isInteger(parsed) || parsed < 100 || parsed > 60000) {
+        throw new Error('invalid_fps_sample_ms');
+    }
+    return parsed;
+}
 function normalizeCaptureAction(raw, index) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`invalid_action:${index}`);
@@ -144,11 +164,17 @@ function buildCaptureRemoteCommandArgs(url, options = {}) {
     if (options.timeout !== undefined) {
         args.push('--timeout', String(parseTimeout(options.timeout)));
     }
+    if (options.settle !== undefined) {
+        args.push('--settle', String(parseSettle(options.settle)));
+    }
     pushOptionalArg(args, '--screenshot', options.screenshot);
     pushOptionalArg(args, '--log', options.log);
     pushOptionalArg(args, '--expected-url', options.expectedUrl);
     pushOptionalArg(args, '--actions', options.actions);
     pushOptionalArg(args, '--viewport', options.viewport);
+    if (options.fpsSampleMs !== undefined) {
+        args.push('--fps-sample-ms', String(parseFpsSampleMs(options.fpsSampleMs)));
+    }
     if (username) {
         args.push('--username', username, '--password', password);
     }
@@ -174,10 +200,12 @@ function parseOptions(url, options = {}) {
         targetUrl: trimmedUrl,
         expectedUrl,
         timeoutSeconds: parseTimeout(options.timeout),
+        settleSeconds: parseSettle(options.settle),
         screenshotPath: (0, node_path_1.resolve)(process.cwd(), options.screenshot?.trim() || 'output/playwright/capture-url.png'),
         logPath: options.log?.trim() ? (0, node_path_1.resolve)(process.cwd(), options.log.trim()) : null,
         actionsPath: options.actions?.trim() ? (0, node_path_1.resolve)(process.cwd(), options.actions.trim()) : null,
         viewport: parseViewport(options.viewport),
+        fpsSampleMs: parseFpsSampleMs(options.fpsSampleMs),
         login: username
             ? {
                 username,
@@ -209,11 +237,21 @@ async function captureRemote(url, options = {}) {
             process.exitCode = 1;
             return;
         }
+        if (error instanceof Error && error.message === 'invalid_settle') {
+            (0, messages_1.printErrorWithHelp)('The --settle value must be a number between 0 and 600 seconds.', [], { command: 'project capture remote' });
+            process.exitCode = 1;
+            return;
+        }
         if (error instanceof Error && error.message === 'invalid_viewport') {
             (0, messages_1.printErrorWithHelp)('The --viewport value must be WIDTHxHEIGHT with each side between 320 and 4096 pixels.', [], { command: 'project capture remote' });
             process.exitCode = 1;
             return;
         }
+        if (error instanceof Error && error.message === 'invalid_fps_sample_ms') {
+            (0, messages_1.printErrorWithHelp)('The --fps-sample-ms value must be an integer between 100 and 60000 milliseconds.', [], { command: 'project capture remote' });
+            process.exitCode = 1;
+            return;
+        }
         if (error instanceof Error && error.message === 'invalid_credentials_pair') {
             (0, messages_1.printErrorWithHelp)('Use --username and --password together.', [], { command: 'project capture remote' });
             process.exitCode = 1;
@@ -272,6 +310,7 @@ async function captureRemote(url, options = {}) {
                 targetUrl: parsed.targetUrl,
                 expectedUrl: parsed.expectedUrl ?? parsed.targetUrl,
                 timeoutMs: Math.round(parsed.timeoutSeconds * 1000),
+                settleAfterReadyMs: Math.round(parsed.settleSeconds * 1000),
                 minimumLogLevel: 'info',
                 screenshotPath: parsed.screenshotPath,
                 logPath: parsed.logPath,
@@ -280,13 +319,14 @@ async function captureRemote(url, options = {}) {
                 login: parsed.login,
                 actions: actions ?? undefined,
                 contextOptions: parsed.viewport ? { viewport: parsed.viewport } : undefined,
+                frameRateSampleMs: parsed.fpsSampleMs ?? undefined,
             });
             if (result.errorCount > 0) {
-                console.error(`[capture] Completed with ${result.errorCount} error(s) after ${parsed.timeoutSeconds} seconds.`);
+                console.error(`[capture] Completed with ${result.errorCount} error(s) after timeout=${parsed.timeoutSeconds}s settle=${parsed.settleSeconds}s.`);
                 process.exitCode = 1;
             }
             else {
-                console.log(`[capture] Completed without console errors after ${parsed.timeoutSeconds} seconds.`);
+                console.log(`[capture] Completed without console errors after timeout=${parsed.timeoutSeconds}s settle=${parsed.settleSeconds}s.`);
             }
         }
         catch (error) {

package/dist/commands/worker/runtime.d.ts

@@ -28,6 +28,13 @@ export type LoggedProcessTranscriptChunk = {
 export declare function readPositiveEnvInt(name: string, fallback: number): number;
 export declare function readEnvBoolean(name: string, fallback: boolean): boolean;
 export declare function extractAgentTokenUsage(output: string): AgentTokenUsage;
+export declare function extractCodexRolloutTokenUsage(output: string): AgentTokenUsage;
+export declare function extractCodexThreadId(output: string): string | null;
+export type CodexRolloutTokenUsageReadOptions = {
+    sessionsRoot?: string;
+    deleteAfterRead?: boolean;
+};
+export declare function readCodexRolloutTokenUsageForThread(threadId: string, options?: CodexRolloutTokenUsageReadOptions): Promise<AgentTokenUsage>;
 export declare function extractCodexTokensUsed(output: string): number | null;
 export declare function assertWorkerTokenUsageWithinCap(input: {
     tokensUsed: number | null;

package/dist/commands/worker/runtime.js

@@ -7,6 +7,9 @@ exports.DEFAULT_TRANSCRIPT_FLUSH_INTERVAL_MS = exports.DEFAULT_CODEX_LOG_TAIL_CH
 exports.readPositiveEnvInt = readPositiveEnvInt;
 exports.readEnvBoolean = readEnvBoolean;
 exports.extractAgentTokenUsage = extractAgentTokenUsage;
+exports.extractCodexRolloutTokenUsage = extractCodexRolloutTokenUsage;
+exports.extractCodexThreadId = extractCodexThreadId;
+exports.readCodexRolloutTokenUsageForThread = readCodexRolloutTokenUsageForThread;
 exports.extractCodexTokensUsed = extractCodexTokensUsed;
 exports.assertWorkerTokenUsageWithinCap = assertWorkerTokenUsageWithinCap;
 exports.runLoggedProcess = runLoggedProcess;
@@ -17,6 +20,8 @@ exports.buildClaudePermissionSettings = buildClaudePermissionSettings;
 exports.buildClaudeDeniedPermissionRules = buildClaudeDeniedPermissionRules;
 exports.buildWorkerChildEnv = buildWorkerChildEnv;
 const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const CHILD_KILL_GRACE_MS = 10000;
 exports.DEFAULT_CODEX_TIMEOUT_MS = 2 * 60 * 60 * 1000;
@@ -59,6 +64,15 @@ function normalizeTokenCount(value) {
     }
     return Math.ceil(value);
 }
+function normalizeFirstTokenCount(...values) {
+    for (const value of values) {
+        const normalized = normalizeTokenCount(value);
+        if (normalized !== null) {
+            return normalized;
+        }
+    }
+    return null;
+}
 function coerceRecord(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         return null;
@@ -91,6 +105,55 @@ function readStructuredUsage(parsed) {
     }
     return null;
 }
+function readCodexRolloutStructuredUsage(parsed) {
+    const root = coerceRecord(parsed);
+    if (!root || root.type !== 'token_count') {
+        return null;
+    }
+    const info = coerceRecord(root.info);
+    return coerceRecord(info?.total_token_usage);
+}
+function normalizeAgentTokenUsageFromRecord(usage) {
+    const outputTokens = normalizeFirstTokenCount(usage.output_tokens, usage.outputTokens);
+    const cacheCreationInputTokens = normalizeFirstTokenCount(usage.cache_creation_input_tokens, usage.cacheCreationInputTokens);
+    const cacheReadInputTokens = normalizeFirstTokenCount(usage.cache_read_input_tokens, usage.cached_input_tokens, usage.cacheReadInputTokens);
+    const rawInputTokens = normalizeFirstTokenCount(usage.input_tokens, usage.inputTokens);
+    const inputTokens = rawInputTokens !== null
+        && cacheReadInputTokens !== null
+        && usage.cached_input_tokens !== undefined
+        ? Math.max(0, rawInputTokens - cacheReadInputTokens)
+        : rawInputTokens;
+    const tokenParts = [
+        inputTokens,
+        outputTokens,
+        cacheCreationInputTokens,
+        cacheReadInputTokens,
+    ];
+    const sawTokenValue = tokenParts.some((value) => value !== null);
+    if (!sawTokenValue) {
+        return null;
+    }
+    return {
+        inputTokens,
+        outputTokens,
+        cacheCreationInputTokens,
+        cacheReadInputTokens,
+        totalTokens: tokenParts.reduce((sum, value) => sum + (value ?? 0), 0),
+        rawProviderUsage: usage,
+        usageParseError: null,
+    };
+}
+function missingAgentTokenUsage(reason = 'agent_usage_not_reported') {
+    return {
+        inputTokens: null,
+        outputTokens: null,
+        cacheCreationInputTokens: null,
+        cacheReadInputTokens: null,
+        totalTokens: null,
+        rawProviderUsage: null,
+        usageParseError: reason,
+    };
+}
 function extractAgentTokenUsage(output) {
     for (const line of output.split(/\r?\n/).reverse()) {
         const trimmed = line.trim();
@@ -103,42 +166,119 @@ function extractAgentTokenUsage(output) {
             if (!usage) {
                 continue;
             }
-            const inputTokens = normalizeTokenCount(usage.input_tokens);
-            const outputTokens = normalizeTokenCount(usage.output_tokens);
-            const cacheCreationInputTokens = normalizeTokenCount(usage.cache_creation_input_tokens);
-            const cacheReadInputTokens = normalizeTokenCount(usage.cache_read_input_tokens);
-            const tokenParts = [
-                inputTokens,
-                outputTokens,
-                cacheCreationInputTokens,
-                cacheReadInputTokens,
-            ];
-            const sawTokenValue = tokenParts.some((value) => value !== null);
-            if (sawTokenValue) {
-                return {
-                    inputTokens,
-                    outputTokens,
-                    cacheCreationInputTokens,
-                    cacheReadInputTokens,
-                    totalTokens: tokenParts.reduce((sum, value) => sum + (value ?? 0), 0),
-                    rawProviderUsage: usage,
-                    usageParseError: null,
-                };
+            const tokenUsage = normalizeAgentTokenUsageFromRecord(usage);
+            if (tokenUsage) {
+                return tokenUsage;
             }
         }
         catch {
             continue;
         }
     }
-    return {
-        inputTokens: null,
-        outputTokens: null,
-        cacheCreationInputTokens: null,
-        cacheReadInputTokens: null,
-        totalTokens: null,
-        rawProviderUsage: null,
-        usageParseError: 'agent_usage_not_reported',
-    };
+    return missingAgentTokenUsage();
+}
+function extractCodexRolloutTokenUsage(output) {
+    for (const line of output.split(/\r?\n/).reverse()) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            const usage = readCodexRolloutStructuredUsage(parsed);
+            if (!usage) {
+                continue;
+            }
+            const tokenUsage = normalizeAgentTokenUsageFromRecord(usage);
+            if (tokenUsage) {
+                return tokenUsage;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return missingAgentTokenUsage();
+}
+function extractCodexThreadId(output) {
+    for (const line of output.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+            continue;
+        }
+        try {
+            const root = coerceRecord(JSON.parse(trimmed));
+            if (!root) {
+                continue;
+            }
+            const type = typeof root.type === 'string' ? root.type : '';
+            const rawThreadId = type === 'thread.started'
+                ? root.thread_id ?? root.threadId
+                : type === 'session_meta'
+                    ? root.session_id ?? root.sessionId
+                    : null;
+            if (typeof rawThreadId === 'string' && rawThreadId.trim()) {
+                return rawThreadId.trim();
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function findCodexRolloutFileForThread(threadId, sessionsRoot) {
+    const stack = [{ dir: sessionsRoot, depth: 0 }];
+    const matches = [];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)(current.dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                continue;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            const entryPath = node_path_1.default.join(current.dir, entry.name);
+            if (entry.isDirectory()) {
+                if (current.depth < 6) {
+                    stack.push({ dir: entryPath, depth: current.depth + 1 });
+                }
+                continue;
+            }
+            if (entry.isFile()
+                && entry.name.startsWith('rollout-')
+                && entry.name.endsWith('.jsonl')
+                && entry.name.includes(threadId)) {
+                matches.push(entryPath);
+            }
+        }
+    }
+    if (matches.length <= 0) {
+        return null;
+    }
+    matches.sort();
+    return matches[matches.length - 1];
+}
+async function readCodexRolloutTokenUsageForThread(threadId, options = {}) {
+    const normalizedThreadId = threadId.trim();
+    if (!normalizedThreadId) {
+        return missingAgentTokenUsage('codex_thread_id_missing');
+    }
+    const sessionsRoot = options.sessionsRoot ?? node_path_1.default.join(node_os_1.default.homedir(), '.codex', 'sessions');
+    const rolloutPath = await findCodexRolloutFileForThread(normalizedThreadId, sessionsRoot);
+    if (!rolloutPath) {
+        return missingAgentTokenUsage('codex_rollout_file_not_found');
+    }
+    const output = await (0, promises_1.readFile)(rolloutPath, 'utf8');
+    if (options.deleteAfterRead !== false) {
+        await (0, promises_1.rm)(rolloutPath, { force: true });
+    }
+    return extractCodexRolloutTokenUsage(output);
 }
 function extractCodexTokensUsed(output) {
     return extractAgentTokenUsage(output).totalTokens;
@@ -285,12 +425,12 @@ function buildCodexExecArgs(input) {
     const sandboxMode = input.sandboxMode ?? 'danger-full-access';
     const args = [
         'exec',
+        '--json',
         '--sandbox',
         sandboxMode,
         '--cd',
         input.workspaceDir,
         '--skip-git-repo-check',
-        '--ephemeral',
         '--model',
         input.model,
         '-c',

package/dist/commands/worker.d.ts

@@ -1,11 +1,11 @@
 import type { ApiClient } from '@playdrop/api-client';
-import { type AgentExecutionTarget, type AgentRuntime, type AgentTaskKind, type AgentTaskResponse, type AgentWorkerCapabilities, type WorkerAgentTaskAssignmentResponse, type WorkerAgentTaskBaseSourceResponse, type WorkerAgentTaskWorkspaceFileResponse, type WorkerClaimAgentTaskResponse } from '@playdrop/types';
+import { type AgentTaskNextStepSuggestion, type AgentExecutionTarget, type AgentRuntime, type AgentTaskKind, type AgentTaskResponse, type AgentWorkerCapabilities, type WorkerAgentTaskAssignmentResponse, type WorkerAgentTaskBaseSourceResponse, type WorkerAgentTaskWorkspaceFileResponse, type WorkerClaimAgentTaskResponse } from '@playdrop/types';
 import { type WorkerPlaydropAssetRequirement } from './upload';
 import { type LoggedProcessResult, type LoggedProcessTranscriptChunk } from './worker/runtime';
-export { DEFAULT_CODEX_TIMEOUT_MS, DEFAULT_WORKER_TOKEN_CAP, assertWorkerTokenUsageWithinCap, buildCodexExecArgs, buildClaudeExecArgs, buildClaudePermissionSettings, buildWorkerChildEnv, extractAgentTokenUsage, extractCodexTokensUsed, readEnvBoolean, readCodexSandboxMode, runLoggedProcess, } from './worker/runtime';
+export { DEFAULT_CODEX_TIMEOUT_MS, DEFAULT_WORKER_TOKEN_CAP, assertWorkerTokenUsageWithinCap, buildCodexExecArgs, buildClaudeExecArgs, buildClaudePermissionSettings, buildWorkerChildEnv, extractAgentTokenUsage, extractCodexRolloutTokenUsage, extractCodexThreadId, extractCodexTokensUsed, readEnvBoolean, readCodexSandboxMode, readCodexRolloutTokenUsageForThread, runLoggedProcess, } from './worker/runtime';
 export type { AgentTokenUsage, LoggedProcessResult, LoggedProcessTranscriptChunk, } from './worker/runtime';
 export declare const WORKER_SESSION_EXPIRED_MESSAGE = "worker session expired: run \"playdrop auth login\" and start the worker again";
-export declare const WORKER_CONTEXT_COMMAND_NOT_ALLOWED_MESSAGE = "worker_context_command_not_allowed: inside a PlayDrop worker task only task progress, task upload/done/fail, assigned remix scaffolding, project validation/build/dev/capture, read-only catalogue/documentation lookup, and PlayDrop AI generation are permitted.";
+export declare const WORKER_CONTEXT_COMMAND_NOT_ALLOWED_MESSAGE = "worker_context_command_not_allowed: inside a PlayDrop worker task only task progress, task claim-slug, task upload/done/fail, assigned app scaffolding, project validation/build/dev/capture, read-only catalogue/documentation lookup, and PlayDrop AI generation are permitted.";
 type WorkerStartOptions = {
     env?: string;
     once?: boolean;
@@ -57,6 +57,8 @@ type TaskReportOptions = {
     phase?: string;
     pct?: string | number;
     message?: string;
+    done?: string;
+    current?: string;
     kind?: string;
 };
 type TaskCatalogueReportOptions = {
@@ -66,6 +68,12 @@ type TaskCatalogueReportOptions = {
 };
 type TaskCompleteOptions = {
     env?: string;
+    nextSteps?: string;
+};
+type TaskClaimSlugOptions = {
+    appName?: string;
+    displayName?: string;
+    env?: string;
 };
 type TaskUploadOptions = {
     env?: string;
@@ -80,6 +88,7 @@ type TaskSubmitReviewOptions = {
     messageFile?: string;
     creatorFeedbackFile?: string;
     evidenceDir?: string;
+    nextSteps?: string;
 };
 export type WorkerHealthAlertInput = {
     state: 'started' | 'stopped' | 'crashed';
@@ -115,6 +124,7 @@ export declare function appendWorkerTranscriptChunks(input: {
     chunks: LoggedProcessTranscriptChunk[];
     batchSize?: number;
 }): Promise<void>;
+export declare function readTaskNextStepsFile(filePath: string | undefined): AgentTaskNextStepSuggestion[] | undefined;
 export declare function assertTaskUploadResultMatchesContext(input: {
     taskContext: {
         taskId: number;
@@ -144,6 +154,8 @@ export declare function readWorkerTaskState(): WorkerTaskState | null;
 export declare function buildWorkerHealthAlertText(input: WorkerHealthAlertInput): string;
 export declare function isWorkerAuthFailureError(error: unknown): boolean;
 export declare function classifyWorkerEventDrainError(error: unknown): 'session_expired' | 'lease_invalid' | null;
+export declare function isWorkerTransientNetworkError(error: unknown): boolean;
+export declare function classifyWorkerHeartbeatError(error: unknown): 'session_expired' | 'lease_invalid' | 'transient_network' | null;
 export declare function assertWorkerClaimErrorRetryable(error: unknown): void;
 export declare function resolvePlaydropAssetRequirementFromText(value: unknown): WorkerPlaydropAssetRequirement | null;
 export declare function loadWorkerEnvFile(envName: string | undefined, cwd?: string): string | null;
@@ -218,6 +230,7 @@ export declare function startWorker(options?: WorkerStartOptions): Promise<void>
 export declare function reportTask(options: TaskReportOptions): Promise<void>;
 export declare function reportCatalogueTask(options: TaskCatalogueReportOptions): Promise<void>;
 export declare function uploadTask(options?: TaskUploadOptions): Promise<void>;
+export declare function claimSlugTask(options: TaskClaimSlugOptions): Promise<void>;
 export declare function completeTask(options: TaskCompleteOptions): Promise<void>;
 export declare function readReviewEvidenceFiles(evidenceDir: string | undefined): Array<{
     name: string;