@crewx/app 0.1.0-rc.17 → 0.1.0-rc.19

package/dist/src/engine.js

@@ -42,6 +42,8 @@ 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;
@@ -97,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)
@@ -115,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');
@@ -131,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) {
@@ -388,15 +396,36 @@ function resolveWorkspaceRoot(startDirectory = process.cwd()) {
         current = parent;
     }
 }
-function readAppManifest(directory) {
+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(path.join(directory, 'ui-plugin.json'), 'utf8'));
+        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);
@@ -584,14 +613,27 @@ 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 }),
     };
 }
+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)
@@ -732,6 +774,41 @@ async function runAction(context, instanceId, actionId, requestId, input, timeou
         },
     };
 }
+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'] ?? '';
@@ -753,6 +830,95 @@ function contextFromEnvironment() {
 function isAppCommandOutcome(value) {
     return 'exitCode' in value;
 }
+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;
@@ -778,6 +944,16 @@ function parseSingleAppCommand(args, command) {
 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)
@@ -816,7 +992,7 @@ async function executeAppCheck(args) {
         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}`];
+        return [`${marker} ${where}  ${code}${manifestReasonSuffix(item)}`];
     });
     lines.push(`Summary: ${errors} errors, ${warnings} warnings`);
     return {
@@ -921,7 +1097,10 @@ function hasBuildScript(appDirectory) {
     }
 }
 function buildOutputPaths(appDirectory) {
-    const result = new Set([path.normalize('ui-plugin.json')]);
+    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)) {
@@ -1172,13 +1351,122 @@ async function executeAppDev(args) {
     }
     return runAppDevWatcher(prepared.context, hasBuildScript(prepared.context.appDirectory));
 }
-async function executeAppCommand(args) {
+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();
@@ -1193,22 +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,
-            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'] }
-                : {}),
-        });
+        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]);
@@ -1246,7 +1525,10 @@ async function executeAppCommand(args) {
     }
     const action = await runAction(context, instanceId, actionId, requestId, parsed.input, RUN_REQUEST_TIMEOUT_MS);
     if (!action.ok)
-        return withRunTimeoutGuidance(action.outcome, requestId);
-    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