@crewx/cli 0.9.0-rc.94 → 0.9.0-rc.96

package/dist/commands/detached.js

@@ -0,0 +1,507 @@
+"use strict";
+/**
+ * Shared receipt-mode implementation for the query and execute commands.
+ *
+ * A receipt is persisted before a detached runner is started. The runner gets
+ * its own identity variables, while the trace variables remain the caller's
+ * trace context and are never repurposed as the runner assignment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractReceiptFlags = extractReceiptFlags;
+exports.resolveReceiptMode = resolveReceiptMode;
+exports.adoptAssignedTask = adoptAssignedTask;
+exports.readDetachedMiddleHop = readDetachedMiddleHop;
+exports.runDetachedMiddle = runDetachedMiddle;
+exports.runDetached = runDetached;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const sdk_1 = require("@crewx/sdk");
+const repository_1 = require("@crewx/sdk/repository");
+const parse_agent_message_1 = require("./parse-agent-message");
+const parse_common_flags_1 = require("./parse-common-flags");
+const resolve_prompt_1 = require("./resolve-prompt");
+const version_1 = require("../utils/version");
+const inherited_trace_1 = require("../utils/inherited-trace");
+const cal_1 = require("./cal");
+const DETACHED_RUNNER_POLL_INTERVAL_MS = 200;
+const DETACHED_RUNNER_ADOPTION_TIMEOUT_MS = 30_000;
+const DETACHED_VALUE_FLAGS = [
+    '--thread',
+    '--provider',
+    '--model',
+    '--metadata',
+    '--config',
+    '-c',
+    '--output-format',
+    '--effort',
+    '--prompt-file',
+    '-f',
+    '--out',
+    '-o',
+];
+const INTERNAL_MIDDLE_FLAG = '--__crewx-detached-middle';
+const INTERNAL_TASK_FLAG = '--__crewx-detached-task';
+const INTERNAL_LOG_FLAG = '--__crewx-detached-log';
+const INTERNAL_TOKEN_FLAG = '--__crewx-detached-token';
+const INTERNAL_TOKEN_ENV = 'CREWX_DETACHED_HOP_TOKEN';
+function isDetachedValueFlag(arg) {
+    return DETACHED_VALUE_FLAGS.some((name) => arg === name || arg.startsWith(`${name}=`));
+}
+function isDetachedPromptFileFlag(arg) {
+    return arg === '--prompt-file'
+        || arg === '-f'
+        || arg.startsWith('--prompt-file=')
+        || arg.startsWith('-f=');
+}
+/**
+ * Remove receipt-selection flags, respecting the `--` literal-args sentinel.
+ */
+function extractReceiptFlags(args) {
+    const rest = [];
+    let detach = false;
+    let wait = false;
+    let escapeMode = false;
+    for (const arg of args) {
+        if (!escapeMode && arg === '--') {
+            escapeMode = true;
+            rest.push(arg);
+            continue;
+        }
+        if (!escapeMode && (arg === '--detach' || arg === '--async')) {
+            detach = true;
+            continue;
+        }
+        if (!escapeMode && (arg === '--wait' || arg.startsWith('--wait='))) {
+            wait = true;
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { detach, wait, rest };
+}
+/** Resolve the receipt/synchronous mode contract shared by q and x. */
+function resolveReceiptMode(options) {
+    if (options.wait)
+        return { receipt: false, reason: 'wait' };
+    // The runner guard is deliberately independent from trace propagation.
+    if (options.detachedRunner)
+        return { receipt: false, reason: 'detached-runner' };
+    if (options.detach)
+        return { receipt: true, reason: 'explicit-detach' };
+    if (options.agentContext)
+        return { receipt: true, reason: 'agent-context' };
+    return { receipt: false, reason: 'default' };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Wait for the pending receipt to be adopted, or for the runner to die. */
+function waitForDetachedRunner(taskRepo, taskId, child, options = {}) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let pollTimer;
+        let timeoutTimer;
+        const cleanup = () => {
+            if (pollTimer !== undefined)
+                clearInterval(pollTimer);
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+        };
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(outcome);
+        };
+        const inspect = (terminalReason, timedOut = false) => {
+            try {
+                const task = taskRepo.getTask(taskId);
+                if (task && task.status !== 'pending') {
+                    finish({ kind: 'adopted' });
+                    return;
+                }
+                if (terminalReason !== undefined) {
+                    finish({ kind: 'exited', reason: terminalReason });
+                    return;
+                }
+                if (timedOut)
+                    finish({ kind: 'timeout' });
+            }
+            catch (error) {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            }
+        };
+        child.on('error', (error) => {
+            inspect(`Runner failed before adopting task: ${errorMessage(error)}`);
+        });
+        child.on('exit', (code, signal) => {
+            if (options.ignoreSuccessfulExit && code === 0 && signal === null)
+                return;
+            const detail = signal ? `signal ${signal}` : `exit ${code ?? 'unknown'}`;
+            inspect(`Runner exited before adopting task (${detail})`);
+        });
+        pollTimer = setInterval(() => inspect(), DETACHED_RUNNER_POLL_INTERVAL_MS);
+        timeoutTimer = setTimeout(() => inspect(undefined, true), DETACHED_RUNNER_ADOPTION_TIMEOUT_MS);
+        inspect();
+    });
+}
+/** Mark a failed receipt only while the parent still owns its pending row. */
+function failDetachedTask(taskRepo, taskId, reason) {
+    try {
+        const transitioned = taskRepo.failPendingTask(taskId, reason);
+        if (transitioned) {
+            process.stderr.write(`Detached task ${taskId} failed: ${reason}\n`);
+            return false;
+        }
+        const task = taskRepo.getTask(taskId);
+        if (task && task.status !== 'pending')
+            return true;
+    }
+    catch (error) {
+        reason += `; could not persist failure: ${errorMessage(error)}`;
+    }
+    process.stderr.write(`Detached task ${taskId} failed: ${reason}\n`);
+    return false;
+}
+function announceDetachedTask(taskRepo, taskId, logPath, reason, verbose, outputFormat, warning) {
+    let status = 'pending';
+    try {
+        const task = taskRepo.getTask(taskId);
+        status = task?.status === 'pending' ? 'pending' : 'running';
+    }
+    catch {
+        // The receipt was already persisted. Keep the output contract stable if a
+        // follow-up status read is temporarily unavailable.
+    }
+    if (outputFormat === 'json') {
+        process.stdout.write(`${JSON.stringify({ taskId, status, mode: 'receipt', logPath })}\n`);
+        return;
+    }
+    if (verbose)
+        process.stderr.write(`mode=receipt reason=${reason}\n`);
+    process.stdout.write(`${taskId}\n`);
+    process.stderr.write(`Task ${taskId} accepted. This ID is the handle (not a PID).\n`);
+    if (warning && verbose)
+        process.stderr.write(`${warning}\n`);
+    const waitSeconds = (0, cal_1.suggestWaitSeconds)({ startedAt: null });
+    (0, cal_1.writeCalFooter)({
+        commandId: 'crewx.receipt',
+        params: { taskId, wait: String(waitSeconds) },
+    });
+}
+/**
+ * Rebuild runner argv from the parsed request. The resolved prompt is passed
+ * as one argv value after `--`, so stdin is never needed by the detached
+ * child and prompt text beginning with a dash remains positional text.
+ */
+function buildDetachedRunnerArgs(filteredArgs, agentRef, finalMessage) {
+    const forwarded = [];
+    for (let i = 0; i < filteredArgs.length; i += 1) {
+        const arg = filteredArgs[i];
+        if (arg === '--')
+            break;
+        if (arg === '--verbose' || arg === '--overdrive') {
+            forwarded.push(arg);
+            continue;
+        }
+        if (arg === '--var') {
+            const value = filteredArgs[i + 1];
+            if (value !== undefined) {
+                forwarded.push(arg, value);
+                i += 1;
+            }
+            continue;
+        }
+        if (arg.startsWith('--var=')) {
+            forwarded.push(arg);
+            continue;
+        }
+        if (!isDetachedValueFlag(arg))
+            continue;
+        if (isDetachedPromptFileFlag(arg)) {
+            // The parent already resolved this file into finalMessage. Forwarding
+            // the original path would make a later child read a mutable file again.
+            if (!arg.includes('='))
+                i += 1;
+            continue;
+        }
+        forwarded.push(arg);
+        if (!arg.includes('=')) {
+            const value = filteredArgs[i + 1];
+            if (value !== undefined) {
+                forwarded.push(value);
+                i += 1;
+            }
+        }
+    }
+    return [
+        ...forwarded,
+        ...(agentRef ? [agentRef] : []),
+        '--',
+        finalMessage,
+    ];
+}
+function runnerCommand(command) {
+    if (command === 'execute')
+        return 'x';
+    if (command === 'query')
+        return 'q';
+    return command;
+}
+/** Build the only environment contract that identifies a detached runner. */
+function buildRunnerEnvironment(taskId) {
+    const env = { ...process.env };
+    delete env[INTERNAL_TOKEN_ENV];
+    env.CREWX_DETACHED_RUNNER = '1';
+    env.CREWX_ASSIGNED_TASK_ID = taskId;
+    return env;
+}
+/**
+ * Claim a pre-issued receipt without overwriting an already-owned row.
+ * Assignment-only leakage is recoverable: discard the stale id and let the
+ * normal SDK path create a fresh task. A real detached runner must fail loud
+ * because its receipt would otherwise point at no execution row.
+ */
+function adoptAssignedTask(taskRepo, taskId, detachedRunner) {
+    if (taskRepo.adoptPendingTask(taskId)) {
+        return { kind: 'adopted', taskId };
+    }
+    const reason = `stale assigned id ${taskId}: expected pending task with pid NULL`;
+    if (detachedRunner) {
+        process.stderr.write(`Detached runner failed to adopt task ${taskId}: ${reason}\n`);
+        return { kind: 'failed' };
+    }
+    process.stderr.write(`${reason}\n`);
+    return { kind: 'stale' };
+}
+function buildMiddleEnvironment(token) {
+    const env = { ...process.env };
+    env[INTERNAL_TOKEN_ENV] = token;
+    return env;
+}
+/**
+ * Read the private Windows middle-hop contract. Invalid direct invocations
+ * are left untouched and therefore fail through the normal unknown-option
+ * path instead of becoming an undocumented public command.
+ */
+function readDetachedMiddleHop(args) {
+    let marker = false;
+    let taskId;
+    let logPath;
+    let token;
+    let escapeMode = false;
+    const runnerArgs = [];
+    for (const arg of args) {
+        if (!escapeMode && arg === '--') {
+            escapeMode = true;
+            runnerArgs.push(arg);
+            continue;
+        }
+        if (!escapeMode && arg === INTERNAL_MIDDLE_FLAG) {
+            marker = true;
+            continue;
+        }
+        if (!escapeMode && arg.startsWith(`${INTERNAL_TASK_FLAG}=`)) {
+            taskId = arg.slice(`${INTERNAL_TASK_FLAG}=`.length);
+            continue;
+        }
+        if (!escapeMode && arg.startsWith(`${INTERNAL_LOG_FLAG}=`)) {
+            logPath = arg.slice(`${INTERNAL_LOG_FLAG}=`.length);
+            continue;
+        }
+        if (!escapeMode && arg.startsWith(`${INTERNAL_TOKEN_FLAG}=`)) {
+            token = arg.slice(`${INTERNAL_TOKEN_FLAG}=`.length);
+            continue;
+        }
+        runnerArgs.push(arg);
+    }
+    if (!marker || !taskId || !logPath || !token || token !== process.env[INTERNAL_TOKEN_ENV]) {
+        return undefined;
+    }
+    return { taskId, logPath, runnerArgs };
+}
+/**
+ * Windows middle hop: transfer a transient log handle to the final runner,
+ * close the middle process's copy, and exit immediately. The parent treats a
+ * successful middle-hop exit as normal and makes adoption a database decision.
+ */
+async function runDetachedMiddle(command, hop) {
+    let logFd;
+    try {
+        const logDir = (0, path_1.dirname)(hop.logPath);
+        if (!(0, fs_1.existsSync)(logDir))
+            (0, fs_1.mkdirSync)(logDir, { recursive: true });
+        logFd = (0, fs_1.openSync)(hop.logPath, 'a');
+        const entry = process.argv[1];
+        const child = (0, child_process_1.spawn)(process.execPath, [entry, runnerCommand(command), ...hop.runnerArgs], {
+            detached: true,
+            windowsHide: true,
+            stdio: ['ignore', logFd, logFd],
+            env: buildRunnerEnvironment(hop.taskId),
+        });
+        (0, fs_1.closeSync)(logFd);
+        logFd = undefined;
+        child.unref();
+    }
+    catch (error) {
+        if (logFd !== undefined)
+            (0, fs_1.closeSync)(logFd);
+        process.stderr.write(`Runner failed before adopting task: ${errorMessage(error)}\n`);
+        process.exit(1);
+        return;
+    }
+    process.exit(0);
+}
+/**
+ * Persist a receipt and launch its detached runner. Unix uses one hop. Windows
+ * uses a short-lived middle hop so the final runner has no live parent link.
+ */
+async function runDetached(command, filteredArgs, reason) {
+    const parsedFlags = (0, parse_common_flags_1.parseCommonFlags)(filteredArgs);
+    const { thread, metadata, promptFile, rest } = parsedFlags;
+    const { agentRef: parsedAgentRef, message } = (0, parse_agent_message_1.parseAgentMessage)(rest);
+    const finalMessage = await (0, resolve_prompt_1.resolvePrompt)(message, promptFile);
+    const agentRef = parsedAgentRef || '@crewx';
+    if (!finalMessage) {
+        console.error('Usage: crewx query/execute [@agent] <message> [options]');
+        console.error('  @agent is optional. Defaults to @crewx when omitted.');
+        console.error('  Task body can also be supplied via stdin pipe or --prompt-file.');
+        process.exit(1);
+        return;
+    }
+    let parsedMetadata;
+    try {
+        parsedMetadata = (0, parse_common_flags_1.parseMetadata)(metadata);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${errorMessage(error)}\n`);
+        process.exit(2);
+        return;
+    }
+    const taskId = (0, sdk_1.generateId)('tsk');
+    const startedAt = new Date().toISOString();
+    const workspacePath = process.cwd();
+    const hasWorkspaceConfig = (0, fs_1.existsSync)((0, path_1.join)(workspacePath, 'crewx.yaml'))
+        || (0, fs_1.existsSync)((0, path_1.join)(workspacePath, 'crewx.yml'));
+    const inheritedTrace = (0, inherited_trace_1.readInheritedTrace)();
+    const taskTrace = inheritedTrace?.rootTraceId || taskId;
+    const taskRepo = new repository_1.TaskRepository();
+    try {
+        taskRepo.startTask({
+            id: taskId,
+            agentId: agentRef.replace(/^@/, ''),
+            prompt: finalMessage,
+            mode: command === 'q' || command === 'query' ? 'query' : 'execute',
+            status: 'pending',
+            startedAt,
+            pid: null,
+            parentTaskId: inheritedTrace?.parentTaskId ?? null,
+            callerAgentId: inheritedTrace?.callerAgentId ?? null,
+            traceId: taskTrace,
+            command: process.argv.join(' '),
+            metadata: Object.keys(parsedMetadata).length > 0 ? JSON.stringify(parsedMetadata) : null,
+            workspaceId: hasWorkspaceConfig ? (0, sdk_1.hashWorkspaceId)(workspacePath) : null,
+            projectId: null,
+            platform: 'cli',
+            crewxVersion: version_1.CLI_VERSION,
+            threadId: thread ?? null,
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Failed to create detached task receipt: ${errorMessage(error)}\n`);
+        process.exit(1);
+        return;
+    }
+    const runnerArgs = buildDetachedRunnerArgs(filteredArgs, agentRef, finalMessage);
+    const commandForRunner = runnerCommand(command);
+    const logDir = (0, path_1.join)((0, os_1.homedir)(), '.crewx', 'logs');
+    const logPath = (0, path_1.join)(logDir, `${taskId}.log`);
+    let logFd;
+    let child;
+    let middleHop = false;
+    try {
+        if (!(0, fs_1.existsSync)(logDir))
+            (0, fs_1.mkdirSync)(logDir, { recursive: true });
+        if (process.platform === 'win32') {
+            middleHop = true;
+            const token = (0, sdk_1.generateId)('req');
+            child = (0, child_process_1.spawn)(process.execPath, [
+                process.argv[1],
+                commandForRunner,
+                INTERNAL_MIDDLE_FLAG,
+                `${INTERNAL_TASK_FLAG}=${taskId}`,
+                `${INTERNAL_LOG_FLAG}=${logPath}`,
+                `${INTERNAL_TOKEN_FLAG}=${token}`,
+                ...runnerArgs,
+            ], {
+                detached: true,
+                windowsHide: true,
+                stdio: 'ignore',
+                env: buildMiddleEnvironment(token),
+            });
+        }
+        else {
+            logFd = (0, fs_1.openSync)(logPath, 'a');
+            child = (0, child_process_1.spawn)(process.execPath, [process.argv[1], commandForRunner, ...runnerArgs], {
+                detached: true,
+                windowsHide: true,
+                stdio: ['ignore', logFd, logFd],
+                env: buildRunnerEnvironment(taskId),
+            });
+            (0, fs_1.closeSync)(logFd);
+            logFd = undefined;
+        }
+        child.unref();
+    }
+    catch (error) {
+        if (logFd !== undefined)
+            (0, fs_1.closeSync)(logFd);
+        const reasonMessage = `Runner failed before adopting task: ${errorMessage(error)}`;
+        if (!failDetachedTask(taskRepo, taskId, reasonMessage))
+            process.exit(1);
+        else {
+            announceDetachedTask(taskRepo, taskId, logPath, reason, parsedFlags.verbose, parsedFlags.outputFormat);
+            process.exit(0);
+        }
+        return;
+    }
+    let outcome;
+    try {
+        outcome = await waitForDetachedRunner(taskRepo, taskId, child, {
+            ignoreSuccessfulExit: middleHop,
+        });
+    }
+    catch (error) {
+        const reasonMessage = `Runner adoption check failed: ${errorMessage(error)}`;
+        if (!failDetachedTask(taskRepo, taskId, reasonMessage))
+            process.exit(1);
+        else {
+            announceDetachedTask(taskRepo, taskId, logPath, reason, parsedFlags.verbose, parsedFlags.outputFormat);
+            process.exit(0);
+        }
+        return;
+    }
+    if (outcome.kind === 'adopted') {
+        announceDetachedTask(taskRepo, taskId, logPath, reason, parsedFlags.verbose, parsedFlags.outputFormat);
+        process.exit(0);
+        return;
+    }
+    if (outcome.kind === 'timeout') {
+        announceDetachedTask(taskRepo, taskId, logPath, reason, parsedFlags.verbose, parsedFlags.outputFormat, `Warning: runner alive, row not yet adopted after ${DETACHED_RUNNER_ADOPTION_TIMEOUT_MS / 1000}s.`);
+        process.exit(0);
+        return;
+    }
+    if (!failDetachedTask(taskRepo, taskId, outcome.reason))
+        process.exit(1);
+    else {
+        announceDetachedTask(taskRepo, taskId, logPath, reason, parsedFlags.verbose, parsedFlags.outputFormat);
+        process.exit(0);
+    }
+}

package/dist/commands/execute.d.ts

@@ -7,22 +7,20 @@
  *   --provider <cli/xxx>     Provider override
  *   --model <name>           Model override (e.g. claude-sonnet-5)
  *   --metadata <json>        Extra metadata JSON (double-quoted object). Propagated to events/hooks/tracing.
- *                           e.g. --metadata='{"workflow_id":"wf-1"}'
  *   --verbose                Debug output mode (default: raw agent response only)
  *   --config/-c <path>       Config file path override
  *   --output-format <fmt>    Output format (json|text|stream-json)
  *   --effort <level>         Model effort (high|medium|low)
- *   -f/--prompt-file <path>  Read task body from file (bypasses cmd.exe argv truncation)
- *   --detach                 Re-spawn as a detached runner; print task-id and exit 0 immediately.
- *                           Ignored when CREWX_TRACE_ID is already set (recursive-spawn guard) or
- *                           on win32 (unsupported — exits with an error).
+ *   -f/--prompt-file <path>  Read task body from file
+ *   --detach/--async         Persist a receipt and launch a detached runner
+ *   --wait                   Force synchronous execution
  *
  * Stdin support:
  *   Pipe or redirect content into crewx x to supply the task body via stdin.
- *   e.g. cat task.md | crewx x "@agent label"
  *   Stdin is ignored when running in an interactive TTY.
  */
 import { type DelegationEmitState } from './emit-trailer';
+export { runDetachedMiddle } from './detached';
 /**
  * Handle `crewx execute <agentRef> <message>` command.
  *