maka-agent 0.2.1-dev.91.20261018 → 0.2.2-dev.97.20261024

package/dist/run-command-core.js

@@ -16,15 +16,18 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { RunQuestionAvailable, RunSessionInterrupted, } from './run-session-result.js';
 import { randomUUID } from 'node:crypto';
 import { realpath, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { isThinkingLevel } from '@maka/core/model-thinking';
 import { normalizeUserSessionName } from '@maka/core/session-name';
 import { selectMakaRunSession } from './run-session-selection.js';
-import { sessionEventSandboxBoundaryFailureReason } from './sandbox-boundary-failure.js';
+import { RuntimeHostOperationError } from '@maka/runtime-host/client';
 import { resolveMakaWorkspaceRoot } from './workspace-root.js';
 const VALUE_FLAGS = new Set([
+    'session',
+    'answer',
     'cwd',
     'connection',
     'model',
@@ -35,13 +38,29 @@ const VALUE_FLAGS = new Set([
     'host',
     'project',
 ]);
-const REPEATABLE_VALUE_FLAGS = new Set();
-const BOOLEAN_FLAGS = new Set(['continue', 'yolo', 'graph']);
+const BOOLEAN_FLAGS = new Set([
+    'continue',
+    'yolo',
+    'graph',
+    'wait',
+    'no-wait',
+    'json',
+    'status',
+    'result',
+    'recap',
+    'queue',
+    'steer',
+    'stop',
+    'approve',
+    'deny',
+]);
 export function parseMakaRunArgs(argv) {
     const positional = [];
     const flags = new Map();
     const booleanFlags = new Set();
     let literal = false;
+    const optionArgs = argv.includes('--') ? argv.slice(0, argv.indexOf('--')) : argv;
+    const selectsSession = optionArgs.includes('--session');
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (!literal && (arg === '--help' || arg === '-h'))
@@ -52,21 +71,18 @@ export function parseMakaRunArgs(argv) {
         }
         if (!literal && arg.startsWith('--')) {
             const name = arg.slice(2);
-            if (BOOLEAN_FLAGS.has(name)) {
-                if (booleanFlags.has(name))
-                    return { kind: 'error', message: `option repeated: ${arg}` };
+            if (BOOLEAN_FLAGS.has(name) || (name === 'resume' && selectsSession)) {
                 booleanFlags.add(name);
                 continue;
             }
             if (!VALUE_FLAGS.has(name))
                 return { kind: 'error', message: `unknown option: ${arg}` };
-            if (!REPEATABLE_VALUE_FLAGS.has(name) && flags.has(name)) {
-                return { kind: 'error', message: `option repeated: ${arg}` };
-            }
             const value = argv[index + 1];
             if (value === undefined || value.startsWith('--')) {
                 return { kind: 'error', message: `option ${arg} needs a value` };
             }
+            if (flags.has(name) && flags.get(name) !== value)
+                return { kind: 'error', message: `conflicting values for ${arg}` };
             flags.set(name, value);
             index += 1;
             continue;
@@ -79,6 +95,92 @@ export function parseMakaRunArgs(argv) {
     if (positional.length > 1) {
         return { kind: 'error', message: 'maka run accepts at most one positional prompt' };
     }
+    const sessionId = flags.get('session');
+    const resumeExecution = booleanFlags.has('resume');
+    if (sessionId !== undefined && !sessionId.trim())
+        return { kind: 'error', message: '--session requires a non-empty Session ID' };
+    if (booleanFlags.has('wait') && booleanFlags.has('no-wait')) {
+        return { kind: 'error', message: '--wait and --no-wait cannot be used together' };
+    }
+    if (booleanFlags.has('queue') && booleanFlags.has('steer')) {
+        return { kind: 'error', message: '--queue and --steer cannot be used together' };
+    }
+    const actions = Number(booleanFlags.has('status') && !booleanFlags.has('recap')) +
+        Number(booleanFlags.has('result')) +
+        Number(booleanFlags.has('recap')) +
+        Number(flags.has('answer')) +
+        Number(resumeExecution) +
+        Number(booleanFlags.has('stop')) +
+        Number(booleanFlags.has('approve')) +
+        Number(booleanFlags.has('deny'));
+    if (actions > 1)
+        return {
+            kind: 'error',
+            message: 'choose one Session action, or combine --status with --recap',
+        };
+    if ((booleanFlags.has('approve') || booleanFlags.has('deny')) && booleanFlags.has('yolo'))
+        return {
+            kind: 'error',
+            message: '--approve/--deny answer only the current sandbox request; do not combine with --yolo',
+        };
+    if (!sessionId && (actions || booleanFlags.has('queue') || booleanFlags.has('steer'))) {
+        return { kind: 'error', message: 'session operations require --session <session-id>' };
+    }
+    if (sessionId && (booleanFlags.has('continue') || flags.has('project'))) {
+        return {
+            kind: 'error',
+            message: '--session cannot be combined with --continue or --project',
+        };
+    }
+    if (sessionId) {
+        const override = ['cwd', 'timeout', 'graph'].find((name) => flags.has(name) || booleanFlags.has(name));
+        if (override)
+            return {
+                kind: 'error',
+                message: `--${override} cannot be used with --session; use saved settings or legacy --resume <id> for run configuration`,
+            };
+        if (flags.has('max-steps') &&
+            (!positional.length || actions || booleanFlags.has('queue') || booleanFlags.has('steer')))
+            return {
+                kind: 'error',
+                message: '--max-steps requires a Session prompt without --queue/--steer',
+            };
+    }
+    if (actions && positional.length)
+        return { kind: 'error', message: 'session actions do not accept a prompt' };
+    if ((booleanFlags.has('queue') || booleanFlags.has('steer')) && (!positional.length || actions)) {
+        return { kind: 'error', message: '--queue and --steer require a prompt' };
+    }
+    if ((booleanFlags.has('status') ||
+        booleanFlags.has('result') ||
+        booleanFlags.has('recap') ||
+        booleanFlags.has('stop')) &&
+        (booleanFlags.has('wait') || booleanFlags.has('no-wait'))) {
+        return {
+            kind: 'error',
+            message: '--status, --result, --recap and --stop do not accept wait options',
+        };
+    }
+    if (booleanFlags.has('graph') && booleanFlags.has('no-wait')) {
+        return { kind: 'error', message: '--graph must wait for its final result' };
+    }
+    let answers;
+    if (flags.has('answer')) {
+        try {
+            const value = JSON.parse(flags.get('answer'));
+            if (!Array.isArray(value) ||
+                value.length === 0 ||
+                value.some((v) => v !== null && typeof v !== 'string'))
+                throw new Error();
+            answers = value;
+        }
+        catch {
+            return {
+                kind: 'error',
+                message: '--answer expects a JSON array of strings or null, e.g. ["Yes"]',
+            };
+        }
+    }
     const prompt = positional[0];
     const timeout = flags.get('timeout');
     const maxSteps = flags.get('max-steps');
@@ -112,6 +214,26 @@ export function parseMakaRunArgs(argv) {
     return {
         kind: 'run',
         options: {
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(booleanFlags.has('wait') ? { wait: true } : {}),
+            ...(booleanFlags.has('no-wait') ? { noWait: true } : {}),
+            ...(booleanFlags.has('json') ? { json: true } : {}),
+            ...(booleanFlags.has('status') ? { status: true } : {}),
+            ...(booleanFlags.has('result') ? { result: true } : {}),
+            ...(booleanFlags.has('recap') ? { recap: true } : {}),
+            ...(resumeExecution ? { resumeExecution: true } : {}),
+            ...(booleanFlags.has('stop') ? { stop: true } : {}),
+            ...(booleanFlags.has('approve')
+                ? { sandboxDecision: 'allow' }
+                : booleanFlags.has('deny')
+                    ? { sandboxDecision: 'deny' }
+                    : {}),
+            ...(answers ? { answers } : {}),
+            ...(booleanFlags.has('steer')
+                ? { placement: 'current_turn' }
+                : booleanFlags.has('queue')
+                    ? { placement: 'next_turn' }
+                    : {}),
             ...(prompt !== undefined && prompt !== '-' ? { prompt } : {}),
             stdinPrompt: prompt === '-',
             ...(flags.get('cwd') !== undefined ? { cwd: flags.get('cwd') } : {}),
@@ -137,9 +259,35 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         return 0;
     }
     if (parsed.kind === 'error') {
-        deps.writeStderr(`maka run: ${parsed.message}\n\n${makaRunHelpText(deps.cliCommand())}\n`);
+        const optionArgs = argv.includes('--') ? argv.slice(0, argv.indexOf('--')) : argv;
+        writeRunError(parsed.message, deps, optionArgs.includes('--json'));
+        if (!optionArgs.includes('--json'))
+            deps.writeStderr(`Run \`${deps.cliCommand()} run --help\` for usage.\n`);
         return 2;
     }
+    if (parsed.options.sessionId) {
+        try {
+            if (!deps.runSession)
+                throw new Error('Session operations are unavailable in this CLI runtime');
+            const options = { ...parsed.options };
+            // Queries and answers must not block reading an unrelated stdin stream.
+            if (options.prompt !== undefined || options.stdinPrompt)
+                options.prompt = await resolveRunPrompt(options, deps);
+            const result = await deps.runSession(options, deps);
+            writeSessionResult(result, deps, options.json === true || options.status === true);
+            const returnsTaskOutcome = options.prompt !== undefined ||
+                options.answers !== undefined ||
+                options.resumeExecution ||
+                options.sandboxDecision !== undefined ||
+                options.wait ||
+                options.result;
+            return result.status === 'failed' && returnsTaskOutcome ? 1 : 0;
+        }
+        catch (error) {
+            writeRunError(error, deps, parsed.options.json === true, parsed.options.sessionId);
+            return error instanceof RunSessionInterrupted ? 130 : 1;
+        }
+    }
     let prompt;
     let selection;
     const workspaceRoot = deps.workspaceRoot();
@@ -168,14 +316,15 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         });
     }
     catch (error) {
-        deps.writeStderr(`maka run: ${errorMessage(error)}\n`);
+        writeRunError(error, deps, parsed.options.json === true, parsed.options.sessionId);
         return 2;
     }
     let outcome;
-    let boundaryFailure = false;
+    let unavailableSandboxRequest = false;
     let context;
     try {
         context = await deps.createContext({
+            ...(parsed.options.noWait ? { noWait: true } : {}),
             workspaceRoot,
             cwd: selection.cwd,
             ...(selection.kind === 'existing' || parsed.options.connection
@@ -200,14 +349,12 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
             ...(parsed.options.hostProfileId ? { hostProfileId: parsed.options.hostProfileId } : {}),
             ...(parsed.options.projectId ? { projectId: parsed.options.projectId } : {}),
             runOutcomeObserver: (result) => {
-                if (result.sandboxBoundary === 'unresolved')
-                    boundaryFailure = true;
                 outcome = result;
             },
         });
     }
     catch (error) {
-        deps.writeStderr(`maka run: ${errorMessage(error)}\n`);
+        writeRunError(error, deps, parsed.options.json === true, parsed.options.sessionId);
         return 2;
     }
     let session;
@@ -243,12 +390,13 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
     }
     catch (error) {
         await context.close();
-        deps.writeStderr(`maka run: ${errorMessage(error)}\n`);
+        writeRunError(error, deps, parsed.options.json === true, parsed.options.sessionId);
         return 2;
     }
     let interrupted = false;
     let timedOut = false;
     let streamFailed = false;
+    let question;
     let stopPromise;
     let resolveStopSignal;
     const stopSignal = new Promise((resolve) => {
@@ -288,20 +436,12 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
                 : {}),
         })) {
             if (event.type === 'sandbox_boundary_request') {
-                boundaryFailure = true;
-                deps.writeStderr('maka run: sandbox boundary expansion is unavailable in non-interactive mode\n');
+                unavailableSandboxRequest = true;
                 await context.runtime.respondToSandboxBoundary(session.id, {
                     requestId: event.requestId,
                     decision: 'deny',
                 });
             }
-            const sandboxFailureReason = sessionEventSandboxBoundaryFailureReason(event);
-            if (sandboxFailureReason) {
-                boundaryFailure = true;
-                deps.writeStderr(sandboxFailureReason === 'requires_bypass'
-                    ? 'maka run: sandbox bypass requires an explicit --yolo\n'
-                    : 'maka run: sandbox boundary expansion is unavailable in non-interactive mode\n');
-            }
         }
         graphActivity?.release();
         if (parsed.options.graph && outcome?.status === 'completed') {
@@ -310,11 +450,12 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         await stopPromise;
     }
     catch (error) {
-        streamFailed = true;
+        question = error instanceof RunQuestionAvailable ? error : undefined;
+        streamFailed = !question;
         graphActivity?.release();
         await stopPromise?.catch(() => undefined);
-        if (!interrupted && !timedOut) {
-            deps.writeStderr(`maka run: ${errorMessage(error)}\n`);
+        if (!interrupted && !timedOut && !question) {
+            writeRunError(error, deps, parsed.options.json === true, session.id);
         }
     }
     finally {
@@ -326,25 +467,59 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
     if (interrupted)
         return 130;
     if (timedOut) {
-        deps.writeStderr(`maka run: timed out after ${parsed.options.timeoutMs}ms\n`);
+        writeRunError(`timed out after ${parsed.options.timeoutMs}ms`, deps, parsed.options.json === true, session.id);
         return 1;
     }
+    if (question) {
+        writeSessionResult(question.result(), deps, true);
+        return 0;
+    }
     if (streamFailed)
         return 1;
-    if (boundaryFailure)
+    if (unavailableSandboxRequest) {
+        writeRunError('sandbox boundary expansion is unavailable in non-interactive mode', deps, parsed.options.json === true, session.id);
         return 1;
+    }
     if (!outcome) {
-        deps.writeStderr('maka run: runtime produced no outcome\n');
+        writeRunError('runtime produced no outcome', deps, parsed.options.json === true, session.id);
         return 1;
     }
+    if (outcome.status === 'running') {
+        writeSessionResult({ sessionId: session.id, status: 'running', submission: 'started' }, deps, true);
+        return 0;
+    }
     if (outcome.status !== 'completed' || outcome.finalOutput === undefined) {
         const detail = outcome.failure?.message ?? outcome.failure?.class ?? 'runtime failure';
-        deps.writeStderr(`maka run: ${detail}\n`);
+        if (parsed.options.json) {
+            writeSessionResult({ sessionId: session.id, status: 'failed', error: detail }, deps, true);
+        }
+        else
+            deps.writeStderr(`maka run: ${detail}\n`);
         return 1;
     }
-    deps.writeStdout(withTrailingNewline(outcome.finalOutput));
+    writeSessionResult({ sessionId: session.id, status: 'completed', finalOutput: outcome.finalOutput }, deps, parsed.options.json === true);
     return 0;
 }
+export function writeSessionResult(result, deps, json) {
+    if (result.error && result.recap === undefined && !json) {
+        deps.writeStderr(`maka run: ${result.error}\n`);
+        return;
+    }
+    const text = result.recap ?? (result.status === 'completed' ? result.finalOutput : undefined);
+    deps.writeStdout(json || text === undefined ? `${JSON.stringify(result)}\n` : withTrailingNewline(text));
+}
+function writeRunError(error, deps, json, sessionId) {
+    const message = errorMessage(error);
+    if (json) {
+        deps.writeStdout(`${JSON.stringify({
+            ...(sessionId ? { sessionId } : {}),
+            error: message,
+            ...(error instanceof RuntimeHostOperationError ? { code: error.code } : {}),
+        })}\n`);
+    }
+    else
+        deps.writeStderr(`maka run: ${message}\n`);
+}
 async function resolveRunPrompt(options, deps) {
     const shouldReadStdin = options.stdinPrompt || !deps.stdinIsTTY();
     const stdin = shouldReadStdin ? await deps.readStdin() : '';
@@ -366,26 +541,59 @@ async function canonicalDirectory(input) {
 function makaRunHelpText(cliCommand) {
     return [
         `Usage: ${cliCommand} run [PROMPT] [options]`,
-        `       ${cliCommand} -p [PROMPT] [options]`,
+        `       ${cliCommand} run --session <id> [PROMPT | ACTION] [options]`,
         '',
-        'Input:',
-        '  -                         Read the complete prompt from stdin',
-        '  PROMPT with piped stdin   Use PROMPT as instruction and stdin as context',
+        'Ordinary runs wait and print the final answer. For parent-agent coordination:',
+        `  ${cliCommand} run "Inspect this project" --no-wait`,
+        `  ${cliCommand} run --session <id> --wait --json`,
         '',
-        'Options:',
-        '  --cwd <path>              Working directory (default: current directory)',
-        '  --connection <slug>       Model connection to use',
-        '  --host <profile-id>       Connect through a saved Runtime Host profile',
-        '  --project <project-id>    Select an existing Project on a remote Host',
-        '  --model <id>              Model to use',
+        'Execution and output:',
+        '  --no-wait                 Submit and return a JSON receipt (persistent Host required)',
+        '  --wait                    Wait for this message/current Turn (default for prompts)',
+        '  --json                    Return JSON, including final answers and recaps',
+        '  --host <profile-id>       Use the same saved Host profile for every Session call',
+        '',
+        'Session actions (--session <id>; model settings below persist before the action):',
+        '  [no action]               Show status, or save supplied model settings without running',
+        '  --status                  Read status, pending questions/approvals, and execution boundary',
+        '  --recap                   Summarize recorded progress with a separate model call',
+        '  --result                  Read the latest Turn result without waiting',
+        '  --answer <json-array>     Answer the current AskUser, e.g. ["Yes",null]',
+        '  --approve / --deny        Decide the single pending sandbox expansion',
+        '  PROMPT                    Queue a new Turn; --steer targets ongoing execution',
+        '  --resume                  Safely continue stopped execution',
+        '  --stop                    Request stop for the current Turn',
+        '',
+        'Model settings (creation or persistent Session updates):',
+        '  --connection <slug>       Select a model connection; otherwise keep the saved account',
+        '  --model <id>              Select a model; otherwise keep the saved model',
         '  --thinking <level>        off|on|minimal|low|medium|high|xhigh|max|default',
+        '',
+        'Run settings (creation or legacy --resume <id>):',
+        '  --cwd <path>              Working directory (default: current directory)',
         '  --timeout <seconds>       Invocation timeout',
-        '  --max-steps <count>       Tool-step cap',
-        '  --yolo                    Give this task full access to your files and network',
-        '  --resume <session-id>     Continue an explicit compatible task',
-        '  --continue                Continue the latest compatible task for cwd',
-        '  --graph                   Run this turn in Graph Mode and wait for graph completion',
+        '  --max-steps <count>       Tool-step cap; also supported for an idle Session prompt',
+        '  --project <project-id>    Select an existing Project on a remote Host',
+        '  --graph                   Run in Graph Mode and wait for graph completion',
+        '  --yolo                    Explicitly grant full access, including on Session execution',
+        '',
+        'Input and compatibility:',
+        '  -                         Read the prompt from stdin; piped stdin otherwise adds context',
+        '  --queue                   Explicit spelling of the default Session prompt placement',
+        '  --steer                   Deliver this prompt to ongoing execution',
+        '  --resume <session-id>     Legacy blocking selector; permits run-setting overrides',
+        '  --continue                Legacy selector for the latest compatible task in cwd',
+        `  ${cliCommand} -p [PROMPT]  Alias for run`,
         '  -h, --help                Show help',
+        '',
+        'Receipts, status, and pending interactions are JSON without an extra --json.',
+        'Check status, not just exit 0: needs_input/needs_approval require a caller decision.',
+        'finalOutput is a task result; recap is progress; submission is admission; configuration is saved settings.',
+        'Combine --status --recap for a JSON snapshot with both state and progress.',
+        '--status/--result/--recap/--stop do not accept wait flags. Recap consumes model usage.',
+        'Errors are brief text on stderr by default; --json returns structured errors on stdout.',
+        'Session controls inherit bypass access too; a read-only prompt does not restrict it.',
+        'Legacy --resume <id> requires --yolo for bypass. --approve/--deny do not switch to bypass.',
     ].join('\n');
 }
 function defaultMakaRunEnvironmentDeps() {