@orchagent/cli 0.3.90 → 0.3.92

package/dist/commands/publish.js

@@ -584,7 +584,7 @@ function registerPublishCommand(program) {
         .option('--skills-locked', 'Lock default skills (callers cannot override via headers)')
         .option('--docker', 'Include Dockerfile for custom environment (builds E2B template)')
         .option('--local-download', 'Allow users to download and run locally (default: server-only)')
-        .option('--no-required-secrets', 'Skip required_secrets check for tool/agent types')
+        .option('--no-required-secrets', '(deprecated) No longer needed — required_secrets defaults to []')
         .option('--all', 'Publish all agents in subdirectories (dependency order)')
         .action(async (options) => {
         const cwd = process.cwd();
@@ -718,44 +718,62 @@ function registerPublishCommand(program) {
             }
             throw new errors_1.CliError(`Failed to read orchagent.json: ${err}`);
         }
+        // UX-1: Collect validation errors and report them all at once
+        const validationErrors = [];
         // Validate manifest
         if (!manifest.name) {
-            throw new errors_1.CliError('orchagent.json must have name');
+            validationErrors.push('orchagent.json must have name');
         }
-        // Validate agent name format (must match gateway rules)
-        const agentNameRegex = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
-        const agentName = manifest.name;
-        if (agentName.length < 2 || agentName.length > 50) {
-            throw new errors_1.CliError('Agent name must be 2-50 characters');
-        }
-        if (agentName !== agentName.toLowerCase()) {
-            throw new errors_1.CliError('Agent name must be lowercase');
-        }
-        if (agentName.length > 1 && !agentNameRegex.test(agentName)) {
-            throw new errors_1.CliError('Agent name must contain only lowercase letters, numbers, and hyphens, and must start/end with a letter or number');
-        }
-        if (agentName.includes('--')) {
-            throw new errors_1.CliError('Agent name must not contain consecutive hyphens');
+        else {
+            // Validate agent name format (must match gateway rules)
+            const agentNameRegex = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+            const agentName = manifest.name;
+            if (agentName.length < 2 || agentName.length > 50) {
+                validationErrors.push('Agent name must be 2-50 characters');
+            }
+            if (agentName !== agentName.toLowerCase()) {
+                validationErrors.push('Agent name must be lowercase');
+            }
+            if (agentName.length > 1 && !agentNameRegex.test(agentName)) {
+                validationErrors.push('Agent name must contain only lowercase letters, numbers, and hyphens, and must start/end with a letter or number');
+            }
+            if (agentName.includes('--')) {
+                validationErrors.push('Agent name must not contain consecutive hyphens');
+            }
         }
         const { canonicalType, rawType } = canonicalizeManifestType(manifest.type);
         const runMode = normalizeRunMode(manifest.run_mode);
         const executionEngine = inferExecutionEngineFromManifest(manifest, rawType);
         const callable = manifest.callable !== undefined ? Boolean(manifest.callable) : true;
         if (canonicalType === 'skill') {
-            throw new errors_1.CliError("Use SKILL.md for publishing skills. Remove orchagent.json and run 'orchagent publish' from a skill directory.");
+            throw new errors_1.CliError('Skills use a different publishing format (SKILL.md with YAML front matter).\n\n' +
+                '  To publish a skill:\n' +
+                '    1. Run: orchagent skill create ' + (manifest.name || '<name>') + '\n' +
+                '    2. Edit the generated SKILL.md with your skill content\n' +
+                '    3. Run: orchagent publish\n\n' +
+                '  orchagent.json is not used for skills — SKILL.md replaces it entirely.\n' +
+                '  See: https://orchagent.io/docs/skills');
         }
         if (runMode === 'always_on' && executionEngine === 'direct_llm') {
-            throw new errors_1.CliError('run_mode=always_on requires runtime.command or loop configuration');
+            validationErrors.push('run_mode=always_on requires runtime.command or loop configuration');
         }
         if (manifest.timeout_seconds !== undefined) {
             if (!Number.isInteger(manifest.timeout_seconds) || manifest.timeout_seconds <= 0) {
-                throw new errors_1.CliError('timeout_seconds must be a positive integer');
+                validationErrors.push('timeout_seconds must be a positive integer');
             }
         }
         // Warn about deprecated prompt field
         if (manifest.prompt) {
             process.stderr.write(chalk_1.default.yellow('Warning: "prompt" field in orchagent.json is ignored. Use prompt.md file instead.\n'));
         }
+        // UX-9: Warn about model (singular) vs default_models
+        if (manifest.model && !manifest.default_models) {
+            const modelVal = manifest.model;
+            process.stderr.write(chalk_1.default.yellow(`\nWarning: "model" field in orchagent.json is not recognized.\n` +
+                `  Use "default_models" instead to set per-provider defaults:\n\n` +
+                `  ${chalk_1.default.cyan(`"default_models": { "anthropic": "${modelVal}" }`)}\n\n` +
+                `  The model resolution order is: caller --model flag → agent default_models → platform default.\n\n`));
+        }
         // Auto-migrate inline schemas to schema.json
         const schemaPath = path_1.default.join(cwd, 'schema.json');
         let schemaFileExists = false;
@@ -789,20 +807,8 @@ function registerPublishCommand(program) {
         const manifestFields = ['manifest_version', 'dependencies', 'max_hops', 'timeout_ms', 'per_call_downstream_cap'];
         const misplacedFields = manifestFields.filter(f => f in manifest && !manifest.manifest);
         if (misplacedFields.length > 0) {
-            throw new errors_1.CliError(`Found manifest fields (${misplacedFields.join(', ')}) at top level of orchagent.json.\n` +
-                `These must be nested under a "manifest" key. Example:\n\n` +
-                `  {\n` +
-                `    "name": "${manifest.name}",\n` +
-                `    "type": "${manifest.type || 'agent'}",\n` +
-                `    "manifest": {\n` +
-                `      "manifest_version": 1,\n` +
-                `      "dependencies": [...],\n` +
-                `      "max_hops": 2,\n` +
-                `      "timeout_ms": 60000,\n` +
-                `      "per_call_downstream_cap": 50\n` +
-                `    }\n` +
-                `  }\n\n` +
-                `See docs/manifest.md for details.`);
+            validationErrors.push(`Found manifest fields (${misplacedFields.join(', ')}) at top level of orchagent.json. ` +
+                `These must be nested under a "manifest" key. See docs/manifest.md for details.`);
         }
         // Read prompt for LLM-driven engines (direct_llm + managed_loop).
         let prompt;
@@ -813,11 +819,11 @@ function registerPublishCommand(program) {
             }
             catch (err) {
                 if (err.code === 'ENOENT') {
-                    throw new errors_1.CliError('No prompt.md found for this agent.\n\n' +
-                        'Create a prompt.md file in the current directory with your prompt template.\n' +
-                        'See: https://orchagent.io/docs/publishing');
+                    validationErrors.push('No prompt.md found. Create a prompt.md file with your prompt template.');
+                }
+                else {
+                    throw err;
                 }
-                throw err;
             }
         }
         // Validate managed-loop specific fields + normalize loop payload
@@ -825,7 +831,7 @@ function registerPublishCommand(program) {
         if (executionEngine === 'managed_loop') {
             if (manifest.max_turns !== undefined) {
                 if (typeof manifest.max_turns !== 'number' || manifest.max_turns < 1 || manifest.max_turns > 50) {
-                    throw new errors_1.CliError('max_turns must be a number between 1 and 50');
+                    validationErrors.push('max_turns must be a number between 1 and 50');
                 }
             }
             const providedLoop = manifest.loop && typeof manifest.loop === 'object'
@@ -849,17 +855,17 @@ function registerPublishCommand(program) {
                 const seenNames = new Set();
                 for (const tool of mergedTools) {
                     if (!tool.name || !tool.command) {
-                        throw new errors_1.CliError(`Invalid custom_tool: each tool must have 'name' and 'command' fields.\n` +
-                            `Found: ${JSON.stringify(tool)}`);
-                    }
-                    if (reservedNames.has(tool.name)) {
-                        throw new errors_1.CliError(`Custom tool '${tool.name}' conflicts with a built-in tool name.\n` +
-                            `Reserved names: ${[...reservedNames].join(', ')}`);
+                        validationErrors.push(`Invalid custom_tool: each tool must have 'name' and 'command' fields. Found: ${JSON.stringify(tool)}`);
                     }
-                    if (seenNames.has(tool.name)) {
-                        throw new errors_1.CliError(`Duplicate custom tool name: '${tool.name}'`);
+                    else {
+                        if (reservedNames.has(tool.name)) {
+                            validationErrors.push(`Custom tool '${tool.name}' conflicts with a built-in tool name. Reserved names: ${[...reservedNames].join(', ')}`);
+                        }
+                        if (seenNames.has(tool.name)) {
+                            validationErrors.push(`Duplicate custom tool name: '${tool.name}'`);
+                        }
+                        seenNames.add(tool.name);
                     }
-                    seenNames.add(tool.name);
                 }
             }
             if (!manifest.supported_providers) {
@@ -921,11 +927,13 @@ function registerPublishCommand(program) {
             }
             if (!options.url) {
                 if (!bundleEntrypoint) {
-                    throw new errors_1.CliError('Tool requires either --url <url> or an entry point file (main.py, app.py, index.js, etc.)');
+                    validationErrors.push('Tool requires either --url <url> or an entry point file (main.py, app.py, index.js, etc.)');
+                }
+                else {
+                    shouldUploadBundle = true;
+                    agentUrl = 'https://tool.internal';
+                    process.stdout.write(`Detected code runtime entrypoint: ${bundleEntrypoint}\n`);
                 }
-                shouldUploadBundle = true;
-                agentUrl = 'https://tool.internal';
-                process.stdout.write(`Detected code runtime entrypoint: ${bundleEntrypoint}\n`);
             }
             let runtimeCommand = manifest.runtime?.command?.trim() || '';
             if (!runtimeCommand && manifest.run_command?.trim()) {
@@ -940,7 +948,7 @@ function registerPublishCommand(program) {
             agentUrl = agentUrl || 'https://prompt-agent.internal';
         }
         if (options.docker && executionEngine !== 'code_runtime') {
-            throw new errors_1.CliError('--docker is only supported for code runtime agents');
+            validationErrors.push('--docker is only supported for code runtime agents');
         }
         // Get org info (workspace-aware — returns workspace org if workspace is active)
         const org = await (0, api_1.getOrg)(config, workspaceId);
@@ -982,23 +990,23 @@ function registerPublishCommand(program) {
                     `  the field to use the default) and republish each dependency.\n\n`);
             }
         }
-        // C-1: Block publish if tool/agent type has no required_secrets declared.
+        // UX-2: Default required_secrets to [] when omitted for tool/agent types.
         // Prompt and skill types are exempt (prompt agents get LLM keys from platform,
         // skills don't run standalone).
-        // An explicit empty array (required_secrets: []) is a valid declaration
-        // meaning "this agent deliberately needs no secrets."
-        // Runs before dry-run so --dry-run catches the same errors as real publish (BUG-11).
         if ((canonicalType === 'tool' || canonicalType === 'agent') &&
-            manifest.required_secrets === undefined &&
-            options.requiredSecrets !== false) {
-            process.stderr.write(chalk_1.default.red(`\nError: ${canonicalType} agents must declare required_secrets in orchagent.json.\n\n`) +
-                `  Add the env vars your code needs at runtime:\n` +
-                `  ${chalk_1.default.cyan('"required_secrets": ["ANTHROPIC_API_KEY", "MY_TOKEN"]')}\n\n` +
-                `  If this agent genuinely needs no secrets, add an empty array:\n` +
-                `  ${chalk_1.default.cyan('"required_secrets": []')}\n\n` +
-                `  These are matched by name against your workspace secrets vault.\n` +
-                `  Use ${chalk_1.default.cyan('--no-required-secrets')} to skip this check.\n`);
-            const err = new errors_1.CliError('Missing required_secrets declaration', errors_1.ExitCodes.INVALID_INPUT);
+            manifest.required_secrets === undefined) {
+            manifest.required_secrets = [];
+            process.stderr.write(chalk_1.default.dim(`  ℹ No required_secrets declared — defaulting to [] (no secrets needed)\n`));
+        }
+        // UX-1: Report all validation errors at once
+        if (validationErrors.length > 0) {
+            if (validationErrors.length === 1) {
+                throw new errors_1.CliError(validationErrors[0]);
+            }
+            const numbered = validationErrors.map((e, i) => `  ${i + 1}. ${e}`).join('\n');
+            process.stderr.write(chalk_1.default.red(`\nFound ${validationErrors.length} validation errors:\n\n`) +
+                numbered + '\n');
+            const err = new errors_1.CliError(`Found ${validationErrors.length} validation errors:\n${numbered}`, errors_1.ExitCodes.INVALID_INPUT);
             err.displayed = true;
             throw err;
         }

package/dist/commands/replay.js

@@ -15,15 +15,24 @@ const output_1 = require("../lib/output");
 async function resolveWorkspaceId(config, slug) {
     const configFile = await (0, config_1.loadConfig)();
     const targetSlug = slug ?? configFile.workspace;
-    if (!targetSlug) {
-        throw new errors_1.CliError('No workspace specified. Use --workspace <slug> or run `orch workspace use <slug>` first.');
-    }
     const response = await (0, api_1.request)(config, 'GET', '/workspaces');
-    const workspace = response.workspaces.find((w) => w.slug === targetSlug);
-    if (!workspace) {
-        throw new errors_1.CliError(`Workspace '${targetSlug}' not found.`);
+    if (targetSlug) {
+        const workspace = response.workspaces.find((w) => w.slug === targetSlug);
+        if (!workspace) {
+            throw new errors_1.CliError(`Workspace '${targetSlug}' not found.`);
+        }
+        return workspace.id;
+    }
+    // No workspace specified — auto-select if user has exactly one
+    if (response.workspaces.length === 0) {
+        throw new errors_1.CliError('No workspaces found. Create one with `orch workspace create <name>`.');
+    }
+    if (response.workspaces.length === 1) {
+        return response.workspaces[0].id;
     }
-    return workspace.id;
+    const slugs = response.workspaces.map((w) => w.slug).join(', ');
+    throw new errors_1.CliError(`Multiple workspaces available: ${slugs}\n` +
+        'Specify one with --workspace <slug> or run `orch workspace use <slug>`.');
 }
 function isUuid(value) {
     return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);

package/dist/commands/run.js

@@ -37,7 +37,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.localCommandForEntrypoint = localCommandForEntrypoint;
+exports.inferFileField = inferFileField;
 exports.validateInputSchema = validateInputSchema;
+exports.tryParseJsonObject = tryParseJsonObject;
 exports.isKeyedFileArg = isKeyedFileArg;
 exports.readKeyedFiles = readKeyedFiles;
 exports.mountDirectory = mountDirectory;
@@ -155,6 +157,13 @@ function warnIfLocalPathReference(jsonBody) {
         // If parsing fails, skip the warning
     }
 }
+/**
+ * Infer which schema field should receive file content.
+ *
+ * Returns the detected field name, or null when the schema has properties
+ * but none of the heuristics can determine the right field.
+ * Returns 'content' (default) only when there is no schema to check against.
+ */
 function inferFileField(inputSchema) {
     if (!inputSchema || typeof inputSchema !== 'object')
         return 'content';
@@ -162,6 +171,7 @@ function inferFileField(inputSchema) {
     if (!props || typeof props !== 'object')
         return 'content';
     const properties = props;
+    // 1. Check well-known content field names
     for (const field of CONTENT_FIELD_NAMES) {
         if (properties[field] && properties[field].type === 'string')
             return field;
@@ -170,12 +180,41 @@ function inferFileField(inputSchema) {
     const stringProps = Object.entries(properties)
         .filter(([, v]) => v.type === 'string')
         .map(([k]) => k);
+    // 2. Only one string property in the schema — use it
     if (stringProps.length === 1)
         return stringProps[0];
+    // 3. Only one required string property — use it
     const requiredStrings = stringProps.filter(k => required.includes(k));
     if (requiredStrings.length === 1)
         return requiredStrings[0];
-    return 'content';
+    // 4. Schema exists but detection is ambiguous — return null so callers
+    //    can surface a clear error instead of silently using the wrong field
+    return null;
+}
+/**
+ * Resolve the file field name, throwing a clear error when auto-detection fails.
+ * Used at call sites where a file is being injected into a JSON payload.
+ */
+function resolveFileField(fileFieldOption, inputSchema) {
+    if (fileFieldOption)
+        return fileFieldOption;
+    const detected = inferFileField(inputSchema);
+    if (detected !== null)
+        return detected;
+    // Detection failed — build a helpful error message
+    const props = inputSchema?.properties;
+    const stringFields = props
+        ? Object.entries(props).filter(([, v]) => v.type === 'string').map(([k]) => k)
+        : [];
+    const fieldList = stringFields.length > 0
+        ? `String fields in schema: ${stringFields.map(f => `"${f}"`).join(', ')}`
+        : 'No string fields found in schema';
+    throw new errors_1.CliError(`Could not determine which input field to use for file content.\n\n` +
+        `${fieldList}\n\n` +
+        `Specify the field explicitly:\n` +
+        `  orch run <agent> --file-field <field> input.json\n` +
+        `  orch run <agent> --data @input.json\n` +
+        `  orch run <agent> --file <field>=input.json`);
 }
 function applySchemaDefaults(body, schema) {
     if (!schema)
@@ -264,6 +303,26 @@ async function readStdin() {
         return null;
     return Buffer.concat(chunks);
 }
+/**
+ * Try to parse a Buffer as a JSON object (not array).
+ * Returns the parsed object on success, null on failure or if the content
+ * is not a JSON object (e.g. array, string, number).
+ */
+function tryParseJsonObject(buf) {
+    const text = buf.toString('utf8').trim();
+    if (!text.startsWith('{'))
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 async function buildMultipartBody(filePaths, metadata) {
     if (!filePaths || filePaths.length === 0) {
         const stdinData = await readStdin();
@@ -2016,7 +2075,7 @@ async function executeCloud(agentRef, file, options) {
             const resolvedBody = await resolveJsonBody(options.data);
             const bodyObj = JSON.parse(resolvedBody);
             if (cloudEngine !== 'code_runtime') {
-                const fieldName = options.fileField || inferFileField(agentMeta.input_schema);
+                const fieldName = resolveFileField(options.fileField, agentMeta.input_schema);
                 if (filePaths.length === 1) {
                     await validateFilePath(filePaths[0]);
                     bodyObj[fieldName] = await promises_1.default.readFile(filePaths[0], 'utf-8');
@@ -2072,7 +2131,7 @@ async function executeCloud(agentRef, file, options) {
             headers['Content-Type'] = 'application/json';
         }
         else if ((filePaths.length > 0 || options.metadata) && cloudEngine !== 'code_runtime') {
-            const fieldName = options.fileField || inferFileField(agentMeta.input_schema);
+            const fieldName = resolveFileField(options.fileField, agentMeta.input_schema);
             let bodyObj = {};
             if (options.metadata) {
                 try {
@@ -2127,13 +2186,39 @@ async function executeCloud(agentRef, file, options) {
             sourceLabel = multipart.sourceLabel;
         }
         else if (llmCredentials) {
-            body = JSON.stringify({ llm_credentials: llmCredentials });
+            // Check for piped JSON stdin to merge with credentials
+            const stdinData = await readStdin();
+            const stdinJson = stdinData ? tryParseJsonObject(stdinData) : null;
+            if (stdinJson) {
+                stdinJson.llm_credentials = llmCredentials;
+                warnInputSchemaErrors(stdinJson, agentMeta.input_schema);
+                body = JSON.stringify(stdinJson);
+                sourceLabel = 'stdin';
+            }
+            else {
+                body = JSON.stringify({ llm_credentials: llmCredentials });
+            }
             headers['Content-Type'] = 'application/json';
         }
         else {
-            const multipart = await buildMultipartBody(undefined, options.metadata);
-            body = multipart.body;
-            sourceLabel = multipart.sourceLabel;
+            // No --data, no --file, no --metadata — check for piped JSON stdin
+            const stdinData = await readStdin();
+            if (stdinData) {
+                const stdinJson = tryParseJsonObject(stdinData);
+                if (stdinJson) {
+                    warnInputSchemaErrors(stdinJson, agentMeta.input_schema);
+                    body = JSON.stringify(stdinJson);
+                    headers['Content-Type'] = 'application/json';
+                    sourceLabel = 'stdin';
+                }
+                else {
+                    // Non-JSON stdin — send as binary file attachment
+                    const form = new FormData();
+                    form.append('files[]', new Blob([new Uint8Array(stdinData)]), 'stdin');
+                    body = form;
+                    sourceLabel = 'stdin';
+                }
+            }
         }
     } // end of non-injection path
     const verboseQs = options.verbose ? '?verbose=true' : '';
@@ -2157,8 +2242,11 @@ async function executeCloud(agentRef, file, options) {
         ? { spinner: null, dispose: () => { } }
         : (0, spinner_1.createElapsedSpinner)(`Running ${org}/${parsed.agent}@${parsed.version}...`);
     spinner?.start();
-    // Streamed sandbox runs can take longer; use 10 min timeout.
-    const timeoutMs = wantStream ? 600000 : undefined;
+    // Streamed sandbox runs can take longer; use 10 min timeout (or --wait-timeout).
+    const waitTimeoutSec = options.waitTimeout ? parseInt(options.waitTimeout, 10) : undefined;
+    const timeoutMs = wantStream
+        ? (waitTimeoutSec && waitTimeoutSec > 0 ? waitTimeoutSec * 1000 : 600000)
+        : undefined;
     let response;
     try {
         response = await (0, api_1.safeFetchWithRetryForCalls)(url, {
@@ -2328,38 +2416,74 @@ async function executeCloud(agentRef, file, options) {
             process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${parsed.agent}@${parsed.version}:\n`));
         }
         let progressErrorShown = false;
-        for await (const { event, data } of parseSSE(response.body)) {
-            if (event === 'progress') {
-                try {
-                    const parsed = JSON.parse(data);
-                    renderProgress(parsed, !!options.verbose);
-                    if (parsed.type === 'error') {
-                        progressErrorShown = true;
+        let streamTimedOut = false;
+        try {
+            for await (const { event, data } of parseSSE(response.body)) {
+                if (event === 'progress') {
+                    try {
+                        const parsed = JSON.parse(data);
+                        renderProgress(parsed, !!options.verbose);
+                        if (parsed.type === 'error') {
+                            progressErrorShown = true;
+                        }
+                    }
+                    catch {
+                        // ignore malformed progress events
                     }
                 }
-                catch {
-                    // ignore malformed progress events
-                }
-            }
-            else if (event === 'result') {
-                try {
-                    finalPayload = JSON.parse(data);
+                else if (event === 'result') {
+                    try {
+                        finalPayload = JSON.parse(data);
+                    }
+                    catch {
+                        finalPayload = data;
+                    }
                 }
-                catch {
-                    finalPayload = data;
+                else if (event === 'error') {
+                    hadError = true;
+                    try {
+                        finalPayload = JSON.parse(data);
+                    }
+                    catch {
+                        finalPayload = data;
+                    }
                 }
             }
-            else if (event === 'error') {
-                hadError = true;
-                try {
-                    finalPayload = JSON.parse(data);
-                }
-                catch {
-                    finalPayload = data;
-                }
+        }
+        catch (streamErr) {
+            // BUG-6: Detect timeout/abort errors — the server-side job may still be running.
+            const errName = streamErr instanceof DOMException ? streamErr.name
+                : streamErr instanceof Error ? streamErr.name
+                    : '';
+            if (errName === 'TimeoutError' || errName === 'AbortError') {
+                streamTimedOut = true;
+            }
+            else {
+                throw streamErr;
             }
         }
         process.stderr.write('\n');
+        // BUG-6: When the stream timed out, the run is likely still in progress on server.
+        if (streamTimedOut) {
+            const runId = response.headers?.get?.('x-run-id');
+            process.stderr.write(chalk_1.default.yellow('\nRun still in progress on server — the CLI stopped waiting.\n') +
+                (runId
+                    ? chalk_1.default.yellow(`Check status with: orch logs ${runId}\n`)
+                    : chalk_1.default.yellow('Check recent runs with: orch runs\n')) +
+                (options.waitTimeout
+                    ? ''
+                    : chalk_1.default.gray('Tip: Use --wait-timeout <seconds> to wait longer.\n')));
+            await (0, analytics_1.track)('cli_run', {
+                agent: `${org}/${parsed.agent}@${parsed.version}`,
+                input_type: hasInjection ? 'file_injection' : unkeyedFileArgs.length > 0 ? 'file' : options.data ? 'json' : 'empty',
+                mode: 'cloud',
+                streamed: true,
+                timed_out: true,
+            });
+            const err = new errors_1.CliError('CLI wait timeout — run still in progress on server', errors_1.ExitCodes.TIMEOUT);
+            err.displayed = true;
+            throw err;
+        }
         await (0, analytics_1.track)('cli_run', {
             agent: `${org}/${parsed.agent}@${parsed.version}`,
             input_type: hasInjection ? 'file_injection' : unkeyedFileArgs.length > 0 ? 'file' : options.data ? 'json' : 'empty',
@@ -2747,6 +2871,7 @@ function registerRunCommand(program) {
         .option('--skills-only <skills>', 'Use only these skills')
         .option('--no-skills', 'Ignore default skills')
         .option('--no-stream', 'Disable real-time streaming for stream-capable sandbox runs')
+        .option('--wait-timeout <seconds>', 'Max seconds to wait for streaming result (default: 600)')
         // Cloud-only options
         .option('--endpoint <endpoint>', 'Override agent endpoint (cloud only)')
         .option('--tenant <tenant>', 'Tenant identifier for multi-tenant callers (cloud only)')