@crewx/app 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/src/engine.js

@@ -35,25 +35,40 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeAppCommand = executeAppCommand;
 const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
 const https = __importStar(require("node:https"));
+const path = __importStar(require("node:path"));
 const node_url_1 = require("node:url");
+const crewx_api_credential_1 = require("@crewx/shared/crewx-api-credential");
+const receipt_wait_js_1 = require("./receipt-wait.js");
+const usage_js_1 = require("./usage.js");
 const REQUEST_TIMEOUT_MS = 15000;
+const RUN_REQUEST_TIMEOUT_MS = 30000;
+const DEV_ACTION_TIMEOUT_MS = 60000;
+const MAX_BUILD_OUTPUT_BYTES = 64 * 1024;
 const APP_ID_PREFIX = 'uic_';
+const APP_DEV_API_PREFIX = '/api/v1';
+const APP_DEV_CAPABILITIES_PATH = '/api/v1/app-dev/capabilities';
+const APP_DEV_SESSIONS_PATH = '/api/v1/app-dev/sessions';
+const APP_DEV_TOO_OLD_EXIT = 12;
+const APP_DEV_CHECK_FAILED_EXIT = 13;
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', '[::1]', 'localhost']);
+const DEFAULT_APP_DEV_ENDPOINT = 'http://localhost:8150';
 const BLOCKED_ROUTE_MESSAGE = 'Do not work around this by clicking the screen or using another browser. Report that you could not use the App route.';
 const UNAUTHORIZED_MESSAGE = 'Do not retry. Report the failure.';
+const REQUEST_TIMED_OUT_MESSAGE = 'The server did not answer in time. Retry once; if it happens again, report it.';
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-function failure(exitCode, code, status) {
-    let stderr;
-    if (exitCode === 3 || exitCode === 9 || exitCode === 10 || exitCode === 11) {
+function failure(exitCode, code, status, message) {
+    let stderr = message;
+    if (!stderr && (exitCode === 3 || exitCode === 9 || exitCode === 10 || exitCode === 11)) {
         stderr = BLOCKED_ROUTE_MESSAGE;
     }
-    else if (exitCode === 4) {
+    else if (!stderr && exitCode === 4) {
         stderr = UNAUTHORIZED_MESSAGE;
     }
     return {
@@ -84,7 +99,7 @@ function parseCommand(args) {
         const separator = arg.indexOf('=');
         const key = separator >= 0 ? arg.slice(2, separator) : arg.slice(2);
         const inlineValue = separator >= 0 ? arg.slice(separator + 1) : undefined;
-        if ((key !== 'input' && key !== 'request-id') || options.has(key))
+        if ((key !== 'input' && key !== 'request-id' && key !== 'wait') || options.has(key))
             return null;
         const value = inlineValue ?? args[index + 1];
         if (value === undefined)
@@ -102,6 +117,8 @@ function parseCommand(args) {
     }
     if (command !== 'run' && (options.has('input') || options.has('request-id')))
         return null;
+    if (command !== 'receipt' && options.has('wait'))
+        return null;
     let input = {};
     if (options.has('input')) {
         const raw = options.get('input');
@@ -118,11 +135,15 @@ function parseCommand(args) {
     const requestId = options.get('request-id');
     if (requestId !== undefined && !REQUEST_ID_PATTERN.test(requestId))
         return null;
+    const waitSeconds = options.has('wait') ? (0, receipt_wait_js_1.parseWaitSeconds)(options.get('wait')) : undefined;
+    if (waitSeconds === null)
+        return null;
     return {
         command,
         positional,
         input,
         ...(requestId !== undefined ? { requestId } : {}),
+        ...(waitSeconds !== undefined ? { waitSeconds } : {}),
     };
 }
 function getEndpoint(raw) {
@@ -194,31 +215,49 @@ function classifyHttpFailure(response) {
     }
     return failure(1, responseErrorCode(data, 'ERROR'), status);
 }
-function networkFailure(error) {
+function networkFailure(error, classifyTimeout = true) {
     const errorCode = isRecord(error) && typeof error['code'] === 'string'
         ? error['code']
         : '';
     const codexBlocked = process.env['CODEX_SANDBOX_NETWORK_DISABLED'] === '1';
     const errnoBlocked = !codexBlocked && (errorCode === 'EPERM' || errorCode === 'EACCES');
-    return codexBlocked || errnoBlocked
-        ? failure(11, 'SANDBOX_BLOCKED', null)
-        : failure(10, 'SERVER_UNREACHABLE', null);
+    if (codexBlocked || errnoBlocked)
+        return failure(11, 'SANDBOX_BLOCKED', null);
+    if (classifyTimeout && errorCode === 'ETIMEDOUT'
+        && isRecord(error) && error['connectionEstablished'] === true) {
+        return failure(14, 'TIMED_OUT', null, REQUEST_TIMED_OUT_MESSAGE);
+    }
+    return failure(10, 'SERVER_UNREACHABLE', null);
+}
+function withRunTimeoutGuidance(outcome, requestId) {
+    if (outcome.exitCode !== 14)
+        return outcome;
+    return {
+        ...outcome,
+        payload: { ...outcome.payload, requestId },
+        stderr: [
+            'The request timed out and its outcome is unknown.',
+            `Retry the same command once with --request-id ${requestId}; the server will return the same request's receipt without running the action twice.`,
+            `If it times out again, report "server response delayed, outcome unknown" with requestId ${requestId}.`,
+            'Do not report success or failure, click the screen, or use another route.',
+        ].join('\n'),
+    };
 }
-function requestJson(context, method, requestPath, body) {
-    const requestFunction = context.endpoint.protocol === 'https:' ? https.request : http.request;
-    const hostname = context.endpoint.hostname === '[::1]'
+function requestJson(endpoint, authorizationToken, method, requestPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const requestFunction = endpoint.protocol === 'https:' ? https.request : http.request;
+    const hostname = endpoint.hostname === '[::1]'
         ? '::1'
-        : context.endpoint.hostname;
-    const port = context.endpoint.port ? Number(context.endpoint.port) : undefined;
+        : endpoint.hostname;
+    const port = endpoint.port ? Number(endpoint.port) : undefined;
     const bodyText = body === undefined ? undefined : JSON.stringify(body);
     const request = requestFunction({
-        protocol: context.endpoint.protocol,
+        protocol: endpoint.protocol,
         hostname,
         ...(port !== undefined ? { port } : {}),
         method,
         path: requestPath,
         headers: {
-            Authorization: `Bearer ${context.ticket}`,
+            Authorization: `Bearer ${authorizationToken}`,
             Accept: 'application/json',
             ...(bodyText !== undefined ? { 'Content-Type': 'application/json' } : {}),
         },
@@ -227,7 +266,7 @@ function requestJson(context, method, requestPath, body) {
         if (status >= 300 && status < 400) {
             response.destroy();
             clearTimeout(timeout);
-            resolveResponse({ status, data: undefined, invalidJson: false });
+            resolveResponse({ status, data: undefined, invalidJson: false, rawText: '' });
             return;
         }
         const chunks = [];
@@ -238,14 +277,15 @@ function requestJson(context, method, requestPath, body) {
             clearTimeout(timeout);
             const raw = chunks.join('');
             try {
-                resolveResponse({ status, data: JSON.parse(raw), invalidJson: false });
+                resolveResponse({ status, data: JSON.parse(raw), invalidJson: false, rawText: raw });
             }
             catch {
-                resolveResponse({ status, data: undefined, invalidJson: true });
+                resolveResponse({ status, data: undefined, invalidJson: true, rawText: raw });
             }
         });
     });
     let socketError;
+    let connectionEstablished = false;
     let resolveResponse;
     let failResponse;
     const result = new Promise((resolve, reject) => {
@@ -255,9 +295,26 @@ function requestJson(context, method, requestPath, body) {
     const timeout = setTimeout(() => {
         const error = new Error('Request timed out');
         error.code = 'ETIMEDOUT';
+        error.connectionEstablished = connectionEstablished;
         request.destroy(error);
-    }, REQUEST_TIMEOUT_MS);
+    }, timeoutMs);
     request.on('socket', (socket) => {
+        const markConnected = () => {
+            connectionEstablished = true;
+        };
+        if (endpoint.protocol === 'https:') {
+            const tlsSocket = socket;
+            if (tlsSocket.authorized)
+                markConnected();
+            else
+                tlsSocket.once('secureConnect', markConnected);
+        }
+        else {
+            if (socket.connecting)
+                socket.once('connect', markConnected);
+            else
+                markConnected();
+        }
         socket.once('error', (error) => {
             socketError = error;
         });
@@ -271,9 +328,9 @@ function requestJson(context, method, requestPath, body) {
     request.end();
     return result;
 }
-async function performRequest(context, method, requestPath, body) {
+async function performRequest(context, method, requestPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
     try {
-        const response = await requestJson(context, method, requestPath, body);
+        const response = await requestJson(context.endpoint, context.ticket, method, requestPath, body, timeoutMs);
         if (response.status < 200 || response.status >= 300) {
             return { ok: false, outcome: classifyHttpFailure(response) };
         }
@@ -293,6 +350,242 @@ async function performRequest(context, method, requestPath, body) {
         return { ok: false, outcome: networkFailure(error) };
     }
 }
+function appDevTooOld(status) {
+    return failure(APP_DEV_TOO_OLD_EXIT, 'SERVER_TOO_OLD', status, 'The running CrewX does not support App dev mode.');
+}
+function appDevCredentialFailure(error) {
+    if (error instanceof crewx_api_credential_1.CrewxCredentialError) {
+        return failure(error.exitCode, error.code, null, error.message);
+    }
+    return failure(1, 'ERROR', null);
+}
+function appDevEndpoint() {
+    const raw = process.env['CREWX_ENDPOINT']?.trim() || DEFAULT_APP_DEV_ENDPOINT;
+    return getEndpoint(raw);
+}
+function isDirectory(directory) {
+    try {
+        return fs.statSync(directory).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isFile(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function resolveWorkspaceRoot(startDirectory = process.cwd()) {
+    let current = path.resolve(startDirectory);
+    while (true) {
+        if (isDirectory(path.join(current, 'apps')) || isFile(path.join(current, 'crewx.yaml'))) {
+            try {
+                return fs.realpathSync(current);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+const APP_MANIFEST_FILE = 'manifest.json';
+const LEGACY_APP_MANIFEST_FILE = 'ui-plugin.json';
+const CREWX_META_NAMESPACE = 'dev.crewx';
+function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readAppManifest(directory) {
+    const legacy = readJsonObject(path.join(directory, LEGACY_APP_MANIFEST_FILE));
+    const modernPath = path.join(directory, APP_MANIFEST_FILE);
+    if (!isFile(modernPath))
+        return legacy;
+    const modern = readJsonObject(modernPath);
+    if (!modern)
+        return undefined;
+    const meta = modern['_meta'];
+    const crewx = isRecord(meta) ? meta[CREWX_META_NAMESPACE] : undefined;
+    const view = {
+        pluginId: modern['name'],
+        entry: isRecord(crewx) ? crewx['entry'] : undefined,
+    };
+    if (legacy && legacy['pluginId'] !== view['pluginId'])
+        return undefined;
+    return view;
+}
+function isPathInside(parentDirectory, candidate) {
+    const relative = path.relative(parentDirectory, candidate);
+    return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function resolveWorkspaceApp(workspacePath, appSelector) {
+    if (!appSelector || appSelector === '.' || appSelector === '..' || /[\\/]/.test(appSelector)) {
+        return failure(2, 'USAGE', null, 'App must be a folder name or pluginId.');
+    }
+    const appsDirectory = path.join(workspacePath, 'apps');
+    const directDirectory = path.join(appsDirectory, appSelector);
+    let appDirectory = isDirectory(directDirectory) ? directDirectory : undefined;
+    if (!appDirectory && isDirectory(appsDirectory)) {
+        try {
+            for (const item of fs.readdirSync(appsDirectory, { withFileTypes: true })) {
+                if (!item.isDirectory())
+                    continue;
+                const candidate = path.join(appsDirectory, item.name);
+                const manifest = readAppManifest(candidate);
+                if (manifest?.['pluginId'] === appSelector) {
+                    appDirectory = candidate;
+                    break;
+                }
+            }
+        }
+        catch {
+        }
+    }
+    let appId = appSelector;
+    if (appDirectory) {
+        try {
+            appDirectory = fs.realpathSync(appDirectory);
+        }
+        catch {
+            return failure(6, 'APP_INVALID', null);
+        }
+        if (!isPathInside(fs.realpathSync(appsDirectory), appDirectory)) {
+            return failure(2, 'USAGE', null, 'App folder must be inside the workspace apps directory.');
+        }
+        const manifest = readAppManifest(appDirectory);
+        if (typeof manifest?.['pluginId'] === 'string' && manifest['pluginId'].length > 0) {
+            appId = manifest['pluginId'];
+        }
+    }
+    else {
+        appDirectory = directDirectory;
+    }
+    return { appId, appDirectory };
+}
+function successEnvelope(response) {
+    if (response.status < 200 || response.status >= 300) {
+        return { ok: false, outcome: classifyHttpFailure(response) };
+    }
+    if (response.invalidJson || !isRecord(response.data) || response.data['success'] !== true
+        || !isRecord(response.data['data'])) {
+        return { ok: false, outcome: failure(1, responseErrorCode(response.data, 'ERROR'), response.status) };
+    }
+    return {
+        ok: true,
+        value: response.data,
+        status: response.status,
+        rawText: response.rawText,
+    };
+}
+async function checkAppDevCapabilities(endpoint, token) {
+    try {
+        const response = await requestJson(endpoint, token, 'GET', APP_DEV_CAPABILITIES_PATH);
+        if (response.status === 404 || (response.status >= 300 && response.status < 400)
+            || response.invalidJson) {
+            return { ok: false, outcome: appDevTooOld(response.status) };
+        }
+        if (response.status < 200 || response.status >= 300) {
+            return { ok: false, outcome: classifyHttpFailure(response) };
+        }
+        if (!isRecord(response.data) || response.data['success'] !== true
+            || !isRecord(response.data['data']) || response.data['data']['appDev'] !== 1) {
+            return { ok: false, outcome: appDevTooOld(response.status) };
+        }
+        return {
+            ok: true,
+            value: response.data,
+            status: response.status,
+            rawText: response.rawText,
+        };
+    }
+    catch (error) {
+        return { ok: false, outcome: networkFailure(error, false) };
+    }
+}
+async function prepareAppDevContext(appSelector) {
+    const endpoint = appDevEndpoint();
+    if (!endpoint)
+        return { ok: false, outcome: failure(9, 'ENDPOINT_REJECTED', null) };
+    let token;
+    try {
+        token = (0, crewx_api_credential_1.resolveCrewxApiCredential)('app-dev').token;
+    }
+    catch (error) {
+        return { ok: false, outcome: appDevCredentialFailure(error) };
+    }
+    const capabilities = await checkAppDevCapabilities(endpoint, token);
+    if (!capabilities.ok)
+        return { ok: false, outcome: capabilities.outcome };
+    const workspacePath = resolveWorkspaceRoot();
+    if (!workspacePath) {
+        return {
+            ok: false,
+            outcome: failure(2, 'WORKSPACE_NOT_FOUND', null, 'No workspace root with apps/ or crewx.yaml was found.'),
+        };
+    }
+    const app = resolveWorkspaceApp(workspacePath, appSelector);
+    if ('exitCode' in app)
+        return { ok: false, outcome: app };
+    let response;
+    try {
+        response = await requestJson(endpoint, token, 'POST', APP_DEV_SESSIONS_PATH, {
+            workspacePath,
+            appId: app.appId,
+        });
+    }
+    catch (error) {
+        return { ok: false, outcome: networkFailure(error, false) };
+    }
+    const opened = successEnvelope(response);
+    if (!opened.ok)
+        return { ok: false, outcome: opened.outcome };
+    const data = opened.value['data'];
+    if (!isRecord(data)
+        || typeof data['workspaceSlug'] !== 'string'
+        || typeof data['appId'] !== 'string'
+        || typeof data['devPath'] !== 'string'
+        || !data['devPath'].startsWith('/ws/')) {
+        return { ok: false, outcome: failure(1, 'ERROR', response.status) };
+    }
+    if (!isDirectory(app.appDirectory)) {
+        return { ok: false, outcome: failure(6, 'APP_INVALID', response.status) };
+    }
+    return {
+        ok: true,
+        context: {
+            endpoint,
+            token,
+            workspacePath,
+            appId: data['appId'],
+            appDirectory: app.appDirectory,
+            devPath: data['devPath'],
+        },
+    };
+}
+function appDevPath(context, ...segments) {
+    return `${APP_DEV_API_PREFIX}${context.devPath}${segments.length > 0 ? `/${segments.map(segment).join('/')}` : ''}`;
+}
+async function performAppDevRequest(context, method, requestPath, body, timeoutMs = REQUEST_TIMEOUT_MS) {
+    try {
+        const response = await requestJson(context.endpoint, context.token, method, requestPath, body, timeoutMs);
+        return successEnvelope(response);
+    }
+    catch (error) {
+        return { ok: false, outcome: networkFailure(error, false) };
+    }
+}
 function appIdFrom(value) {
     const direct = value['appId'] ?? value['id'];
     if (typeof direct === 'string' && direct.length > 0)
@@ -320,16 +613,29 @@ function projectLauncher(value) {
     if (!appId || !definitionHash)
         return undefined;
     const actions = value['agentActions'];
+    const agentAccess = projectAgentAccess(value['agentAccess']);
     return {
         appId,
         name: typeof value['name'] === 'string' ? value['name'] : '',
         description: typeof value['description'] === 'string' ? value['description'] : '',
         definitionHash,
         agentActions: Array.isArray(actions) ? actions : [],
+        ...(agentAccess === undefined ? {} : { agentAccess }),
     };
 }
-async function loadLaunchers(context) {
-    const response = await performRequest(context, 'GET', pathFor(context, 'ui-instances', 'apps'));
+const AGENT_ACCESS_LEVELS = new Set(['allowed', 'approval_required', 'denied']);
+function projectAgentAccess(value) {
+    if (!isRecord(value))
+        return undefined;
+    const levels = new Map();
+    for (const [actionId, level] of Object.entries(value)) {
+        if (AGENT_ACCESS_LEVELS.has(level))
+            levels.set(actionId, level);
+    }
+    return levels.size > 0 ? levels : undefined;
+}
+async function loadLaunchers(context, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const response = await performRequest(context, 'GET', pathFor(context, 'ui-instances', 'apps'), undefined, timeoutMs);
     if (!response.ok)
         return response;
     const apps = response.value['apps'];
@@ -345,11 +651,11 @@ async function loadLaunchers(context) {
 function findLauncher(apps, appId) {
     return apps.find((app) => app.appId === appId);
 }
-async function openLauncher(context, launcher) {
+async function openLauncher(context, launcher, timeoutMs = REQUEST_TIMEOUT_MS) {
     const response = await performRequest(context, 'POST', pathFor(context, 'ui-instances', 'open'), {
         appId: launcher.appId,
         expectedDefinitionHash: launcher.definitionHash,
-    });
+    }, timeoutMs);
     if (!response.ok)
         return response;
     const instance = isRecord(response.value['instance']) ? response.value['instance'] : response.value;
@@ -408,8 +714,8 @@ async function readInstanceState(context, instanceId) {
         },
     };
 }
-async function runAction(context, instanceId, actionId, requestId, input) {
-    const response = await performRequest(context, 'POST', pathFor(context, 'ui-instances', instanceId, 'actions'), { actionId, requestId, input });
+async function runAction(context, instanceId, actionId, requestId, input, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const response = await performRequest(context, 'POST', pathFor(context, 'ui-instances', instanceId, 'actions'), { actionId, requestId, input }, timeoutMs);
     if (!response.ok)
         return response;
     const receipt = response.value['receipt'];
@@ -459,10 +765,50 @@ async function runAction(context, instanceId, actionId, requestId, input) {
             actionId: typeof receipt['actionId'] === 'string' ? receipt['actionId'] : actionId,
             status,
             outcome: Object.prototype.hasOwnProperty.call(receipt, 'outcome') ? receipt['outcome'] : null,
+            ...(typeof receipt['errorCode'] === 'string' ? { errorCode: receipt['errorCode'] } : {}),
             state: ai && Object.prototype.hasOwnProperty.call(ai, 'state') ? ai['state'] : null,
+            ...(Object.prototype.hasOwnProperty.call(response.value, 'result') ? { result: response.value['result'] } : {}),
+            ...(Object.prototype.hasOwnProperty.call(response.value, 'resultExpired')
+                ? { resultExpired: response.value['resultExpired'] }
+                : {}),
         },
     };
 }
+function isRetryablePollFailure(outcome) {
+    const error = outcome.payload['error'];
+    return outcome.exitCode === 14
+        || (isRecord(error) && error['status'] === 429);
+}
+async function readReceipt(context, receiptId) {
+    const response = await performRequest(context, 'GET', pathFor(context, 'ui-action-receipts', receiptId));
+    if (!response.ok) {
+        return { state: 'failed', retryable: isRetryablePollFailure(response.outcome), value: response.outcome };
+    }
+    const receipt = response.value['receipt'];
+    if (!isRecord(receipt))
+        return { state: 'failed', retryable: false, value: failure(1, 'ERROR', response.status) };
+    return {
+        state: receipt['status'] === 'requested' ? 'pending' : 'settled',
+        value: success({
+            ok: true,
+            receipt,
+            outcome: Object.prototype.hasOwnProperty.call(receipt, 'outcome') ? receipt['outcome'] : null,
+            ...(typeof receipt['errorCode'] === 'string' ? { errorCode: receipt['errorCode'] } : {}),
+            ...(Object.prototype.hasOwnProperty.call(response.value, 'result') ? { result: response.value['result'] } : {}),
+            ...(Object.prototype.hasOwnProperty.call(response.value, 'resultExpired')
+                ? { resultExpired: response.value['resultExpired'] }
+                : {}),
+        }),
+    };
+}
+function receiptStillPending(receiptId, waitedSeconds) {
+    return {
+        exitCode: 124,
+        payload: { ok: false, exit: 124, error: { code: 'WAIT_TIMEOUT', status: null }, receiptId },
+        suppressOutput: true,
+        stderr: `→ Receipt ${receiptId} is still pending after ${waitedSeconds}s. Do not end your turn: run crewx app receipt ${receiptId} --wait=${(0, receipt_wait_js_1.nextWaitSeconds)(waitedSeconds)} again.`,
+    };
+}
 function contextFromEnvironment() {
     const ticket = process.env['CREWX_TASK_TICKET'] ?? '';
     const workspaceSlug = process.env['CREWX_WORKSPACE_SLUG'] ?? '';
@@ -484,7 +830,643 @@ function contextFromEnvironment() {
 function isAppCommandOutcome(value) {
     return 'exitCode' in value;
 }
-async function executeAppCommand(args) {
+function padTime(value) {
+    return String(value).padStart(2, '0');
+}
+function localExpiryTime(expiresAt) {
+    const date = typeof expiresAt === 'number'
+        ? new Date(expiresAt)
+        : typeof expiresAt === 'string'
+            ? new Date(/^\d+$/.test(expiresAt) ? Number(expiresAt) : expiresAt)
+            : undefined;
+    if (!date || Number.isNaN(date.getTime()))
+        return undefined;
+    return `${padTime(date.getHours())}:${padTime(date.getMinutes())}`;
+}
+function withApprovalHint(outcome) {
+    if (outcome.exitCode !== 8)
+        return outcome;
+    const time = localExpiryTime(outcome.payload['expiresAt']);
+    const receiptId = outcome.payload['receiptId'];
+    const lines = [
+        `→ Waiting for the user's approval in the App window${time ? ` (expires ${time})` : ''}. Do not end your turn: ending it cancels the request.`,
+        ...(typeof receiptId === 'string' && receiptId.length > 0
+            ? [`→ Wait: crewx app receipt ${receiptId} --wait=${receipt_wait_js_1.RECEIPT_WAIT_DEFAULT_SECONDS} (repeat on exit 124 until it settles)`]
+            : []),
+        '→ Report success only if it settles as succeeded.',
+    ];
+    return { ...outcome, stderr: [outcome.stderr, ...lines].filter(Boolean).join('\n') };
+}
+const MANUAL_READ_LIMIT_BYTES = 256 * 1024;
+function readAppManual(appDirectory) {
+    try {
+        const realDirectory = fs.realpathSync(appDirectory);
+        const realFile = fs.realpathSync(path.join(realDirectory, 'SKILL.md'));
+        if (!isPathInside(realDirectory, realFile) || !isFile(realFile))
+            return undefined;
+        const descriptor = fs.openSync(realFile, 'r');
+        try {
+            const bytes = new Uint8Array(MANUAL_READ_LIMIT_BYTES);
+            const bytesRead = fs.readSync(descriptor, bytes, 0, bytes.length, 0);
+            return (0, usage_js_1.manualBody)(Buffer.from(bytes.buffer, 0, bytesRead).toString('utf8'));
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+async function findLocalApp(appId) {
+    const root = resolveWorkspaceRoot();
+    if (!root)
+        return undefined;
+    try {
+        const sdk = await Promise.resolve().then(() => __importStar(require('@crewx/sdk')));
+        const discovered = await sdk.discoverWorkspaceApps(root);
+        const candidate = discovered.apps.find((app) => app.appId === appId)
+            ?? discovered.apps.find((app) => app.pluginId === appId);
+        if (!candidate)
+            return undefined;
+        return {
+            candidate,
+            directory: path.join(root, candidate.relativePath),
+            resolveAccess: sdk.resolveAgentAccess,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function executeAppUsage(args) {
+    if (args.length !== 2 || args[1].startsWith('--'))
+        return usageFailure();
+    const appId = args[1];
+    const context = contextFromEnvironment();
+    if (isAppCommandOutcome(context))
+        return context;
+    const list = await loadLaunchers(context);
+    if (!list.ok)
+        return list.outcome;
+    const launcher = findLauncher(list.value, appId);
+    if (!launcher)
+        return failure(6, 'MCP_APP_NOT_FOUND', null);
+    const serverActions = launcher.agentActions.filter((item) => typeof item === 'string');
+    const local = await findLocalApp(appId);
+    const text = local
+        ? (0, usage_js_1.renderUsage)(readAppManual(local.directory), (0, usage_js_1.renderActionsSection)(appId, local.candidate, (0, usage_js_1.buildActionRows)(local.candidate, new Set(serverActions), (action) => local.resolveAccess(action), launcher.agentAccess)), local.candidate.manifest.csp?.connectDomains)
+        : (0, usage_js_1.renderUsage)(undefined, (0, usage_js_1.renderServerOnlyActions)(appId, serverActions));
+    return { exitCode: 0, payload: { ok: true }, stdout: text };
+}
+function parseSingleAppCommand(args, command) {
+    if (args[0] !== command)
+        return null;
+    const positional = [];
+    let flag = false;
+    for (const arg of args.slice(1)) {
+        if (arg === (command === 'dev' ? '--no-open' : '--json')) {
+            if (flag)
+                return null;
+            flag = true;
+        }
+        else if (arg.startsWith('--')) {
+            return null;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length !== 1)
+        return null;
+    return { appSelector: positional[0], flag };
+}
+function standardJsonOutput(outcome) {
+    return `${JSON.stringify(outcome.payload)}\n`;
+}
+function manifestReasonSuffix(item) {
+    const detail = item['detail'];
+    if (item['rule'] !== 'manifest' || !isRecord(detail))
+        return '';
+    const path = typeof detail['path'] === 'string' ? detail['path'] : '';
+    const rule = typeof detail['rule'] === 'string' ? detail['rule'] : '';
+    if (!rule)
+        return '';
+    return `  ${path ? `${path} ` : ''}(${rule})`;
+}
+async function executeAppCheck(args) {
+    const parsed = parseSingleAppCommand(args, 'check');
+    if (!parsed)
+        return usageFailure();
+    const prepared = await prepareAppDevContext(parsed.appSelector);
+    if (!prepared.ok)
+        return prepared.outcome;
+    const response = await performAppDevRequest(prepared.context, 'GET', appDevPath(prepared.context, 'check'));
+    if (!response.ok)
+        return response.outcome;
+    const data = response.value['data'];
+    if (!isRecord(data))
+        return failure(1, 'ERROR', response.status);
+    const summary = isRecord(data['summary']) ? data['summary'] : {};
+    const items = Array.isArray(data['items']) ? data['items'] : [];
+    const errors = typeof summary['errors'] === 'number'
+        ? summary['errors']
+        : items.filter((item) => isRecord(item) && item['severity'] === 'error').length;
+    const warnings = typeof summary['warnings'] === 'number'
+        ? summary['warnings']
+        : items.filter((item) => isRecord(item) && item['severity'] === 'warning').length;
+    const exitCode = errors === 0 ? 0 : APP_DEV_CHECK_FAILED_EXIT;
+    if (parsed.flag) {
+        return {
+            exitCode,
+            payload: response.value,
+            stdout: `${response.rawText ?? standardJsonOutput({ exitCode, payload: response.value })}`
+                + (response.rawText?.endsWith('\n') ? '' : '\n'),
+            suppressOutput: true,
+        };
+    }
+    const lines = items.flatMap((item) => {
+        if (!isRecord(item))
+            return [];
+        const severity = item['severity'];
+        const marker = severity === 'error' ? '✕' : severity === 'ok' ? '✓' : '!';
+        const where = typeof item['where'] === 'string' ? item['where'] : '';
+        const code = typeof item['code'] === 'string' ? item['code'] : '';
+        return [`${marker} ${where}  ${code}${manifestReasonSuffix(item)}`];
+    });
+    lines.push(`Summary: ${errors} errors, ${warnings} warnings`);
+    return {
+        exitCode,
+        payload: {},
+        stdout: `${lines.join('\n')}\n`,
+        suppressOutput: true,
+    };
+}
+async function getPairingDevUrl(context) {
+    let pairingToken;
+    try {
+        pairingToken = (0, crewx_api_credential_1.resolveCrewxApiCredential)('pairing').token;
+    }
+    catch (error) {
+        return appDevCredentialFailure(error);
+    }
+    let response;
+    try {
+        response = await requestJson(context.endpoint, pairingToken, 'POST', '/api/v1/auth/local/code');
+    }
+    catch (error) {
+        return networkFailure(error, false);
+    }
+    if (response.status < 200 || response.status >= 300) {
+        return classifyHttpFailure(response);
+    }
+    if (response.invalidJson || !isRecord(response.data) || typeof response.data['url'] !== 'string') {
+        return failure(1, 'PAIRING_CODE_INVALID', response.status);
+    }
+    try {
+        const pairingUrl = new node_url_1.URL(response.data['url']);
+        const pairingEndpoint = getEndpoint(pairingUrl.origin);
+        const match = pairingUrl.hash.match(/^#pair=(.+)$/);
+        if (!pairingEndpoint || !match)
+            return failure(1, 'PAIRING_CODE_INVALID', response.status);
+        return `${pairingEndpoint.origin}${context.devPath}#pair=${encodeURIComponent(match[1])}`;
+    }
+    catch {
+        return failure(1, 'PAIRING_CODE_INVALID', response.status);
+    }
+}
+async function openPlatformUrl(url) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32' ? 'explorer.exe' : 'xdg-open';
+    const child = (0, node_child_process_1.spawn)(command, [url], { detached: true, stdio: 'ignore' });
+    await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+async function executeAppDevAction(args) {
+    const parsed = parseCommand(['run', ...args.slice(2)]);
+    if (!parsed || parsed.command !== 'run')
+        return usageFailure();
+    const [appSelector, actionId] = parsed.positional;
+    const prepared = await prepareAppDevContext(appSelector);
+    if (!prepared.ok)
+        return prepared.outcome;
+    const state = await performAppDevRequest(prepared.context, 'GET', appDevPath(prepared.context, 'state'));
+    if (!state.ok)
+        return state.outcome;
+    const stateData = state.value['data'];
+    if (!isRecord(stateData) || typeof stateData['revision'] !== 'number') {
+        return failure(1, 'APP_DEV_RESPONSE_INVALID', state.status);
+    }
+    const requestId = parsed.requestId ?? `cxa_${(0, node_crypto_1.randomBytes)(16).toString('base64url')}`;
+    const response = await performAppDevRequest(prepared.context, 'POST', appDevPath(prepared.context, 'actions'), {
+        actionId,
+        requestId,
+        input: parsed.input,
+        expectedRevision: stateData['revision'],
+    }, DEV_ACTION_TIMEOUT_MS);
+    if (!response.ok)
+        return response.outcome;
+    const responseData = response.value['data'];
+    const receipt = isRecord(responseData) && isRecord(responseData['receipt'])
+        ? responseData['receipt']
+        : undefined;
+    return {
+        exitCode: receipt?.['outcome'] === 'succeeded' ? 0 : 1,
+        payload: response.value,
+        stdout: `${response.rawText ?? standardJsonOutput({ exitCode: 0, payload: response.value })}`
+            + (response.rawText?.endsWith('\n') ? '' : '\n'),
+        suppressOutput: true,
+    };
+}
+function hasBuildScript(appDirectory) {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(path.join(appDirectory, 'package.json'), 'utf8'));
+        if (!isRecord(packageJson) || !isRecord(packageJson['scripts']))
+            return false;
+        const build = packageJson['scripts']['build'];
+        return typeof build === 'string' && build.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function buildOutputPaths(appDirectory) {
+    const result = new Set([
+        path.normalize(APP_MANIFEST_FILE),
+        path.normalize(LEGACY_APP_MANIFEST_FILE),
+    ]);
+    const manifest = readAppManifest(appDirectory);
+    const entry = manifest?.['entry'];
+    if (typeof entry === 'string' && entry.length > 0 && !path.isAbsolute(entry)) {
+        const normalized = path.normalize(entry);
+        if (normalized !== '..' && !normalized.startsWith(`..${path.sep}`))
+            result.add(normalized);
+    }
+    return result;
+}
+function outputFingerprint(appDirectory, relativePath) {
+    try {
+        const stats = fs.statSync(path.join(appDirectory, relativePath));
+        return `${stats.size}:${stats.mtimeMs}:${stats.ino}`;
+    }
+    catch {
+        return null;
+    }
+}
+function snapshotBuildOutputs(appDirectory, paths) {
+    return new Map([...paths].map((relativePath) => [
+        relativePath,
+        outputFingerprint(appDirectory, relativePath),
+    ]));
+}
+function runNpmBuild(appDirectory, onChild) {
+    const startedAt = Date.now();
+    let output = '';
+    let settled = false;
+    const appendOutput = (chunk) => {
+        const next = Buffer.from(output + (Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk), 'utf8');
+        output = next.length > MAX_BUILD_OUTPUT_BYTES
+            ? next.subarray(next.length - MAX_BUILD_OUTPUT_BYTES).toString('utf8')
+            : next.toString('utf8');
+    };
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)('npm', ['run', 'build'], {
+            cwd: appDirectory,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        onChild(child);
+        child.stdout?.on('data', appendOutput);
+        child.stderr?.on('data', appendOutput);
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            onChild(undefined);
+            resolve({
+                ok,
+                ms: Math.max(0, Date.now() - startedAt),
+                output,
+            });
+        };
+        child.once('error', (error) => {
+            appendOutput(`${error.message}\n`);
+            finish(false);
+        });
+        child.once('close', (code) => finish(code === 0));
+    });
+}
+function responseCode(outcome) {
+    const error = outcome.payload['error'];
+    return isRecord(error) && typeof error['code'] === 'string' ? error['code'] : 'ERROR';
+}
+async function postAppDevReload(context, body) {
+    const response = await performAppDevRequest(context, 'POST', appDevPath(context, 'reload'), body);
+    if (!response.ok)
+        return { errorCode: responseCode(response.outcome) };
+    const data = response.value['data'];
+    return isRecord(data) && typeof data['generation'] === 'number'
+        ? { generation: data['generation'] }
+        : { errorCode: 'APP_DEV_RESPONSE_INVALID' };
+}
+async function runAppDevWatcher(context, buildEnabled) {
+    const parentPid = process.ppid;
+    let watcher;
+    try {
+        watcher = fs.watch(context.appDirectory, { recursive: true }, (_event, filename) => {
+            onFileChange(filename);
+        });
+    }
+    catch (error) {
+        return failure(1, 'WATCH_FAILED', null, error instanceof Error ? error.message : 'Unable to watch the App folder.');
+    }
+    let closed = false;
+    let stopRequested = false;
+    let cycleRunning = false;
+    let queuedChange = false;
+    let queuedPath = '';
+    let pendingPath = '';
+    let debounceTimer;
+    let parentCheckTimer;
+    let activeBuild;
+    let finalOutcome = { exitCode: 0, payload: {}, suppressOutput: true };
+    const recentOutputEvents = new Map();
+    let resolveRun;
+    const result = new Promise((resolve) => {
+        resolveRun = resolve;
+    });
+    const writeLine = (line) => {
+        process.stdout.write(`${line}\n`);
+    };
+    const finish = () => {
+        if (closed)
+            return;
+        closed = true;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        if (parentCheckTimer)
+            clearInterval(parentCheckTimer);
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        resolveRun(finalOutcome);
+    };
+    const onSignal = () => {
+        if (stopRequested)
+            return;
+        stopRequested = true;
+        watcher.close();
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        if (activeBuild && activeBuild.exitCode === null)
+            activeBuild.kill('SIGTERM');
+        if (!cycleRunning)
+            finish();
+    };
+    const onFileChange = (filename) => {
+        if (stopRequested || closed)
+            return;
+        const relativePath = filename === null ? '' : path.normalize(filename.toString());
+        const parts = relativePath.split(path.sep);
+        if (parts.some((part) => part === 'node_modules' || part === '.crewx' || part === 'dist'))
+            return;
+        const outputPaths = buildEnabled ? buildOutputPaths(context.appDirectory) : new Set();
+        if (activeBuild && outputPaths.has(relativePath))
+            return;
+        const suppressedUntil = recentOutputEvents.get(relativePath);
+        if (suppressedUntil !== undefined) {
+            if (Date.now() <= suppressedUntil)
+                return;
+            recentOutputEvents.delete(relativePath);
+        }
+        if (cycleRunning) {
+            queuedChange = true;
+            queuedPath = relativePath || 'App files';
+            return;
+        }
+        pendingPath = relativePath || 'App files';
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            debounceTimer = undefined;
+            const changedPath = pendingPath || 'App files';
+            pendingPath = '';
+            void runCycle(changedPath, false);
+        }, 200);
+    };
+    const reloadLabel = async (body) => {
+        const reload = await postAppDevReload(context, body);
+        return reload.generation === undefined ? `failed ${reload.errorCode ?? 'ERROR'}` : String(reload.generation);
+    };
+    const runCycle = async (changedPath, initial) => {
+        if (stopRequested || closed)
+            return;
+        cycleRunning = true;
+        if (buildEnabled) {
+            const outputPaths = buildOutputPaths(context.appDirectory);
+            const before = snapshotBuildOutputs(context.appDirectory, outputPaths);
+            const build = await runNpmBuild(context.appDirectory, (child) => {
+                activeBuild = child;
+            });
+            const after = snapshotBuildOutputs(context.appDirectory, outputPaths);
+            for (const [outputPath, fingerprint] of after) {
+                if (before.get(outputPath) !== fingerprint) {
+                    recentOutputEvents.set(outputPath, Date.now() + 1000);
+                }
+            }
+            if (stopRequested) {
+                cycleRunning = false;
+                finish();
+                return;
+            }
+            const reloadBody = {
+                reason: 'build',
+                build: {
+                    ok: build.ok,
+                    ms: build.ms,
+                    ...(!build.ok ? { output: build.output } : {}),
+                },
+            };
+            const generationLabel = await reloadLabel(reloadBody);
+            writeLine(`${initial ? 'initial' : changedPath} -> build ${build.ok ? 'ok' : 'failed'} ${build.ms}ms -> reload ${generationLabel}`);
+        }
+        else if (!initial) {
+            const generationLabel = await reloadLabel({ reason: 'manual' });
+            writeLine(`${changedPath} -> reload ${generationLabel}`);
+        }
+        cycleRunning = false;
+        if (stopRequested) {
+            finish();
+            return;
+        }
+        if (queuedChange) {
+            const nextPath = queuedPath || 'App files';
+            queuedChange = false;
+            queuedPath = '';
+            void runCycle(nextPath, false);
+            return;
+        }
+        if (stopRequested)
+            finish();
+    };
+    watcher.once('error', (error) => {
+        finalOutcome = failure(1, 'WATCH_FAILED', null, error.message);
+        onSignal();
+    });
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    parentCheckTimer = setInterval(() => {
+        if (process.ppid !== parentPid)
+            onSignal();
+    }, 1000);
+    parentCheckTimer.unref();
+    if (buildEnabled)
+        void runCycle('initial', true);
+    return result;
+}
+async function executeAppDev(args) {
+    const parsed = parseSingleAppCommand(args, 'dev');
+    if (!parsed)
+        return usageFailure();
+    const prepared = await prepareAppDevContext(parsed.appSelector);
+    if (!prepared.ok)
+        return prepared.outcome;
+    const browserUrl = `${prepared.context.endpoint.origin}${prepared.context.devPath}`;
+    process.stdout.write(`${browserUrl}\n`);
+    if (!parsed.flag) {
+        const pairingUrl = await getPairingDevUrl(prepared.context);
+        if (typeof pairingUrl !== 'string')
+            return pairingUrl;
+        try {
+            await openPlatformUrl(pairingUrl);
+        }
+        catch (error) {
+            return failure(1, 'BROWSER_OPEN_FAILED', null, error instanceof Error ? error.message : 'Could not open the App dev tab.');
+        }
+    }
+    return runAppDevWatcher(prepared.context, hasBuildScript(prepared.context.appDirectory));
+}
+const BUILD_USAGE = 'usage: crewx app build [<appDir>] [--check | --watch]';
+const APP_HELP = [
+    'crewx app <command>',
+    '',
+    '  list                                                   List Apps available to this task',
+    '  open <appId>                                           Open an App in this conversation',
+    '  state <instanceId>                                     Read AI-visible state, buttons, and agent access',
+    '  run <instanceId|appId> <actionId> [--input <JSON>|-] [--request-id <id>]   Run one available action',
+    '  receipt <receiptId> [--wait=<seconds>]                 Read a safe action receipt',
+    '  build [<appDir>] [--check | --watch]                   Build a @Tool App: server.ts -> dist/ and the manifest.json actions',
+    '  dev <app> [--no-open]                                  Start a foreground App dev session',
+    '  check <app> [--json]                                   Run the App dev checks',
+    '  run --dev <app> <actionId> [--input <JSON>|-]          Run an App action through the dev checks',
+    '  usage [<appId>]                                        Show the guide, or one App\'s manual and action table',
+    '',
+].join('\n');
+const BUILD_HELP = [
+    BUILD_USAGE,
+    '',
+    '  Builds <appDir> (default: the current directory) from its server.ts: dist/server.mjs, dist/entry.mjs,',
+    '  and the actions of manifest.json. --check writes nothing and exits 1 when a generated file is stale.',
+    '  --watch rebuilds on every change until Ctrl-C.',
+    '',
+].join('\n');
+function loadAppBuilder() {
+    const candidates = [
+        path.join(__dirname, '..', '..', 'build-app', 'load.cjs'),
+        path.join(__dirname, '..', 'build-app', 'load.cjs'),
+    ];
+    const shim = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!shim)
+        return Promise.reject(new Error('the App build is not part of this install'));
+    return require(shim).loadAppBuilder();
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function executeAppBuild(args) {
+    if (args.slice(1).some((arg) => arg === '--help' || arg === '-h')) {
+        return { exitCode: 0, payload: { ok: true }, stdout: BUILD_HELP };
+    }
+    let builder;
+    try {
+        builder = await loadAppBuilder();
+    }
+    catch (error) {
+        return failure(1, 'BUILD_UNAVAILABLE', null, describeError(error));
+    }
+    let options;
+    try {
+        options = builder.parseArguments(args.slice(1));
+    }
+    catch (error) {
+        return failure(2, 'USAGE', null, `${describeError(error)} → ${BUILD_USAGE}`);
+    }
+    const { appDirectory } = options;
+    const shownDirectory = path.relative(process.cwd(), appDirectory);
+    const rebuildCommand = shownDirectory === '' ? 'crewx app build' : `crewx app build ${shownDirectory}`;
+    if (options.watch) {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            await builder.watchApp(appDirectory, (line) => process.stdout.write(`${line}\n`), { signal: controller.signal });
+        }
+        finally {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+        return { exitCode: 0, payload: {}, suppressOutput: true };
+    }
+    try {
+        const result = await builder.buildApp({ appDirectory, check: options.check });
+        if (options.check && result.staleFiles.length > 0) {
+            return {
+                ...failure(1, 'BUILD_STALE', null, `Stale generated files: ${result.staleFiles.join(', ')} → Fix: ${rebuildCommand}`),
+                payload: {
+                    ok: false,
+                    exit: 1,
+                    error: { code: 'BUILD_STALE', status: null },
+                    appDir: appDirectory,
+                    stale: result.staleFiles,
+                },
+            };
+        }
+        if (options.check) {
+            return success({ ok: true, appDir: appDirectory, check: true, inSync: true, files: result.files, actions: result.actions });
+        }
+        const name = path.basename(appDirectory);
+        const inWorkspaceApps = path.basename(path.dirname(appDirectory)) === 'apps';
+        return {
+            ...success({ ok: true, appDir: appDirectory, files: result.files, actions: result.actions }),
+            stderr: inWorkspaceApps
+                ? `→ Next: crewx app check ${name}`
+                : `→ Next: put ${name} in the workspace apps/ folder, then crewx app check ${name}`,
+        };
+    }
+    catch (error) {
+        return failure(1, 'BUILD_FAILED', null, describeError(error));
+    }
+}
+async function executeAppCommand(args, { clock = receipt_wait_js_1.realClock } = {}) {
+    if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+        return { exitCode: 0, payload: { ok: true }, stdout: APP_HELP };
+    }
+    if (args[0] === 'build')
+        return executeAppBuild(args);
+    if (args[0] === 'dev')
+        return executeAppDev(args);
+    if (args[0] === 'check')
+        return executeAppCheck(args);
+    if (args[0] === 'run' && args[1] === '--dev')
+        return executeAppDevAction(args);
+    if (args[0] === 'usage')
+        return executeAppUsage(args);
     const parsed = parseCommand(args);
     if (!parsed)
         return usageFailure();
@@ -499,13 +1481,13 @@ async function executeAppCommand(args) {
     }
     if (parsed.command === 'receipt') {
         const receiptId = parsed.positional[0];
-        const response = await performRequest(context, 'GET', pathFor(context, 'ui-action-receipts', receiptId));
-        if (!response.ok)
-            return response.outcome;
-        const receipt = response.value['receipt'];
-        if (!isRecord(receipt))
-            return failure(1, 'ERROR', response.status);
-        return success({ ok: true, receipt });
+        const waitSeconds = (0, receipt_wait_js_1.clampWaitSeconds)(parsed.waitSeconds ?? 0);
+        if (waitSeconds === 0)
+            return (await readReceipt(context, receiptId)).value;
+        const last = await (0, receipt_wait_js_1.pollUntilSettled)(() => readReceipt(context, receiptId), waitSeconds, clock);
+        if (last.state !== 'pending')
+            return last.value;
+        return receiptStillPending(receiptId, waitSeconds);
     }
     if (parsed.command === 'state') {
         const result = await readInstanceState(context, parsed.positional[0]);
@@ -530,20 +1512,23 @@ async function executeAppCommand(args) {
     const requestId = parsed.requestId ?? `cxa_${(0, node_crypto_1.randomBytes)(16).toString('base64url')}`;
     let instanceId = target;
     if (!target.startsWith(APP_ID_PREFIX)) {
-        const list = await loadLaunchers(context);
+        const list = await loadLaunchers(context, RUN_REQUEST_TIMEOUT_MS);
         if (!list.ok)
-            return list.outcome;
+            return withRunTimeoutGuidance(list.outcome, requestId);
         const launcher = findLauncher(list.value, target);
         if (!launcher)
             return failure(6, 'MCP_APP_NOT_FOUND', null);
-        const opened = await openLauncher(context, launcher);
+        const opened = await openLauncher(context, launcher, RUN_REQUEST_TIMEOUT_MS);
         if (!opened.ok)
-            return opened.outcome;
+            return withRunTimeoutGuidance(opened.outcome, requestId);
         instanceId = opened.value.instanceId;
     }
-    const action = await runAction(context, instanceId, actionId, requestId, parsed.input);
+    const action = await runAction(context, instanceId, actionId, requestId, parsed.input, RUN_REQUEST_TIMEOUT_MS);
     if (!action.ok)
-        return action.outcome;
-    return success({ ok: true, ...action.value });
+        return withApprovalHint(withRunTimeoutGuidance(action.outcome, requestId));
+    return {
+        ...success({ ok: true, ...action.value }),
+        stderr: `→ Check: crewx app state ${action.value.instanceId}`,
+    };
 }
 //# sourceMappingURL=engine.js.map