@orchagent/cli 0.3.49 → 0.3.52

package/dist/commands/run.js

@@ -36,11 +36,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isKeyedFileArg = isKeyedFileArg;
+exports.readKeyedFiles = readKeyedFiles;
+exports.mountDirectory = mountDirectory;
+exports.buildInjectedPayload = buildInjectedPayload;
 exports.registerRunCommand = registerRunCommand;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
@@ -49,6 +54,7 @@ const spinner_1 = require("../lib/spinner");
 const llm_1 = require("../lib/llm");
 const analytics_1 = require("../lib/analytics");
 const pricing_1 = require("../lib/pricing");
+const package_json_1 = __importDefault(require("../../package.json"));
 const DEFAULT_VERSION = 'latest';
 const AGENTS_DIR = path_1.default.join(os_1.default.homedir(), '.orchagent', 'agents');
 // Local execution environment variables
@@ -219,6 +225,164 @@ async function resolveJsonBody(input) {
         throw (0, errors_1.jsonInputError)('data');
     }
 }
+// ─── Keyed file & mount helpers ──────────────────────────────────────────────
+const KEYED_FILE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function isKeyedFileArg(arg) {
+    const eqIndex = arg.indexOf('=');
+    if (eqIndex <= 0)
+        return null;
+    const key = arg.slice(0, eqIndex);
+    const filePath = arg.slice(eqIndex + 1);
+    if (!KEYED_FILE_KEY_RE.test(key))
+        return null;
+    if (!filePath)
+        return null;
+    return { key, filePath };
+}
+async function readKeyedFiles(args) {
+    const result = {};
+    for (const arg of args) {
+        const parsed = isKeyedFileArg(arg);
+        if (!parsed)
+            continue;
+        const resolved = path_1.default.resolve(parsed.filePath);
+        let stat;
+        try {
+            stat = await promises_1.default.stat(resolved);
+        }
+        catch {
+            throw new errors_1.CliError(`File not found: ${parsed.filePath}`);
+        }
+        if (!stat.isFile()) {
+            throw new errors_1.CliError(`Not a file: ${parsed.filePath}`);
+        }
+        result[parsed.key] = await promises_1.default.readFile(resolved, 'utf-8');
+    }
+    return result;
+}
+const MOUNT_SKIP_DIRS = new Set([
+    'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build',
+    '.next', 'target', '.cache', '.tox', 'coverage', '__snapshots__',
+]);
+const MOUNT_MAX_DEPTH = 15;
+const MOUNT_MAX_FILES = 500;
+async function mountDirectory(dirPath) {
+    const resolved = path_1.default.resolve(dirPath);
+    let stat;
+    try {
+        stat = await promises_1.default.stat(resolved);
+    }
+    catch {
+        throw new errors_1.CliError(`Directory not found: ${dirPath}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new errors_1.CliError(`Not a directory: ${dirPath}`);
+    }
+    const result = {};
+    let fileCount = 0;
+    async function walk(currentPath, relativePath, depth) {
+        if (depth > MOUNT_MAX_DEPTH)
+            return;
+        let names;
+        try {
+            names = await promises_1.default.readdir(currentPath);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.startsWith('.'))
+                continue;
+            if (MOUNT_SKIP_DIRS.has(name))
+                continue;
+            const fullPath = path_1.default.join(currentPath, name);
+            const relPath = relativePath ? `${relativePath}/${name}` : name;
+            // Stat the entry (also skips symlinks)
+            let entryStat;
+            try {
+                entryStat = await promises_1.default.lstat(fullPath);
+                if (entryStat.isSymbolicLink())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (entryStat.isDirectory()) {
+                await walk(fullPath, relPath, depth + 1);
+            }
+            else if (entryStat.isFile()) {
+                if (fileCount >= MOUNT_MAX_FILES) {
+                    throw new errors_1.CliError(`Mount exceeds ${MOUNT_MAX_FILES} files. Use a more specific path or fewer files.`);
+                }
+                try {
+                    const content = await promises_1.default.readFile(fullPath, 'utf-8');
+                    result[relPath] = content;
+                    fileCount++;
+                }
+                catch {
+                    // Skip binary/unreadable files silently
+                }
+            }
+        }
+    }
+    await walk(resolved, '', 0);
+    return result;
+}
+const INJECT_MAX_BYTES = 4 * 1024 * 1024; // 4MB
+async function buildInjectedPayload(options) {
+    let merged = {};
+    // 1. Start with --data
+    if (options.dataOption) {
+        const resolved = await resolveJsonBody(options.dataOption);
+        merged = JSON.parse(resolved);
+    }
+    let totalBytes = 0;
+    // 2. Overlay keyed --file entries
+    if (options.fileArgs && options.fileArgs.length > 0) {
+        const keyedFiles = await readKeyedFiles(options.fileArgs);
+        for (const [key, content] of Object.entries(keyedFiles)) {
+            totalBytes += Buffer.byteLength(content, 'utf-8');
+            merged[key] = content;
+        }
+    }
+    // 3. Overlay --mount entries
+    if (options.mountArgs && options.mountArgs.length > 0) {
+        for (const mountArg of options.mountArgs) {
+            const eqIndex = mountArg.indexOf('=');
+            if (eqIndex <= 0) {
+                throw new errors_1.CliError(`Invalid --mount format: ${mountArg}. Use --mount field=dir`);
+            }
+            const field = mountArg.slice(0, eqIndex);
+            const dirPath = mountArg.slice(eqIndex + 1);
+            if (!KEYED_FILE_KEY_RE.test(field)) {
+                throw new errors_1.CliError(`Invalid mount field name: ${field}. Must be a valid identifier.`);
+            }
+            const fileMap = await mountDirectory(dirPath);
+            for (const content of Object.values(fileMap)) {
+                totalBytes += Buffer.byteLength(content, 'utf-8');
+            }
+            merged[field] = fileMap;
+        }
+    }
+    // 4. Enforce size limit
+    if (totalBytes > INJECT_MAX_BYTES) {
+        throw new errors_1.CliError(`File content exceeds 4MB limit (${(totalBytes / 1024 / 1024).toFixed(1)}MB). ` +
+            `Use a more specific path or fewer files.`);
+    }
+    // 5. Inject llm_credentials
+    if (options.llmCredentials) {
+        merged.llm_credentials = options.llmCredentials;
+    }
+    const parts = [];
+    if (options.fileArgs && options.fileArgs.length > 0) {
+        parts.push(`${options.fileArgs.length} file(s)`);
+    }
+    if (options.mountArgs && options.mountArgs.length > 0) {
+        parts.push(`${options.mountArgs.length} mount(s)`);
+    }
+    const sourceLabel = parts.join(' + ');
+    return { body: JSON.stringify(merged), sourceLabel };
+}
 // ─── Local execution helpers ────────────────────────────────────────────────
 async function downloadAgent(config, org, agent, version) {
     // Try public endpoint first
@@ -529,6 +693,183 @@ async function executePromptLocally(agentData, inputData, skillPrompts = [], con
         return await (0, llm_1.callLlm)(provider, key, model, prompt, agentData.output_schema);
     }, { successText: `Completed with ${provider}` });
 }
+// ─── Local agent-type execution ──────────────────────────────────────────────
+const AGENT_RUNNER_SDK_PACKAGES = {
+    anthropic: 'anthropic',
+    openai: 'openai',
+    gemini: 'google-genai',
+};
+async function executeAgentLocally(agentDir, prompt, inputData, outputSchema, customTools, manifest, config, providerOverride, modelOverride) {
+    // 1. Check Python 3 available
+    try {
+        const { code } = await runCommand('python3', ['--version']);
+        if (code !== 0)
+            throw new Error();
+    }
+    catch {
+        throw new errors_1.CliError('Python 3 is required for local agent execution.\n' +
+            'Install Python 3: https://python.org/downloads');
+    }
+    // 2. Detect LLM provider + key
+    const supportedProviders = manifest?.supported_providers || ['any'];
+    const providersToCheck = providerOverride
+        ? [providerOverride]
+        : supportedProviders;
+    const allProviders = await detectAllLlmKeys(providersToCheck, config);
+    if (allProviders.length === 0) {
+        const providers = providersToCheck.join(', ');
+        throw new errors_1.CliError(`No LLM key found for: ${providers}\n` +
+            `Set an environment variable (e.g., ANTHROPIC_API_KEY), run 'orchagent keys add <provider>', or configure in web dashboard`);
+    }
+    const primary = allProviders[0];
+    const model = modelOverride || primary.model || (0, llm_1.getDefaultModel)(primary.provider);
+    const providerName = primary.provider;
+    const apiKeyEnvVar = llm_1.PROVIDER_ENV_VARS[providerName];
+    // 3. Check LLM SDK installed
+    const sdkPackage = AGENT_RUNNER_SDK_PACKAGES[providerName] || 'anthropic';
+    const sdkImportName = providerName === 'gemini' ? 'google.genai' : sdkPackage;
+    try {
+        const { code } = await runCommand('python3', ['-c', `import ${sdkImportName}`]);
+        if (code !== 0) {
+            process.stderr.write(`Installing ${sdkPackage} Python SDK...\n`);
+            const install = await runCommand('python3', ['-m', 'pip', 'install', '-q', sdkPackage]);
+            if (install.code !== 0) {
+                throw new errors_1.CliError(`Failed to install ${sdkPackage} SDK.\n` +
+                    `Install manually: pip install ${sdkPackage}`);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof errors_1.CliError)
+            throw err;
+        throw new errors_1.CliError(`Failed to check Python SDK: ${err}`);
+    }
+    // 4. Create temp directory with agent files
+    const tempDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-agent-local-${Date.now()}`);
+    await promises_1.default.mkdir(tempDir, { recursive: true });
+    try {
+        // Copy agent_runner.py from resources
+        const runnerSource = path_1.default.join(__dirname, '..', 'resources', 'agent_runner.py');
+        // Also check alternate path for dev mode (running from src/)
+        let runnerContent;
+        try {
+            runnerContent = await promises_1.default.readFile(runnerSource, 'utf-8');
+        }
+        catch {
+            // Fallback for dev: try src/resources relative to the project
+            const altSource = path_1.default.join(__dirname, '..', '..', 'src', 'resources', 'agent_runner.py');
+            try {
+                runnerContent = await promises_1.default.readFile(altSource, 'utf-8');
+            }
+            catch {
+                throw new errors_1.CliError('Agent runner script not found. This is a packaging error.\n' +
+                    'Please reinstall the CLI: npm install -g @orchagent/cli');
+            }
+        }
+        await promises_1.default.writeFile(path_1.default.join(tempDir, 'agent_runner.py'), runnerContent);
+        await promises_1.default.writeFile(path_1.default.join(tempDir, 'prompt.md'), prompt);
+        await promises_1.default.writeFile(path_1.default.join(tempDir, 'input.json'), JSON.stringify(inputData, null, 2));
+        if (outputSchema) {
+            await promises_1.default.writeFile(path_1.default.join(tempDir, 'output_schema.json'), JSON.stringify(outputSchema));
+        }
+        if (customTools && customTools.length > 0) {
+            await promises_1.default.writeFile(path_1.default.join(tempDir, 'custom_tools.json'), JSON.stringify(customTools));
+        }
+        // 5. Set env vars
+        const subprocessEnv = { ...process.env };
+        subprocessEnv.LOCAL_MODE = '1';
+        subprocessEnv.LLM_PROVIDER = providerName;
+        subprocessEnv.LLM_MODEL = model;
+        if (apiKeyEnvVar && primary.apiKey) {
+            subprocessEnv[apiKeyEnvVar] = primary.apiKey;
+        }
+        // 6. Print warning and run
+        process.stderr.write(chalk_1.default.yellow('\nWarning: Local mode. Bash commands execute on your machine (no sandbox).\n\n'));
+        process.stderr.write(`Running with ${providerName} (${model})...\n`);
+        const maxTurns = 25;
+        const proc = (0, child_process_1.spawn)('python3', ['agent_runner.py', '--max-turns', String(maxTurns), '--verbose'], {
+            cwd: tempDir,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: subprocessEnv,
+        });
+        proc.stdin.end();
+        let stdout = '';
+        let stderr = '';
+        proc.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        let lastUsage = null;
+        proc.stderr?.on('data', (data) => {
+            const text = data.toString();
+            stderr += text;
+            // Filter out heartbeat dots and orchagent events, show human-readable lines
+            for (const line of text.split('\n')) {
+                if (line.startsWith('@@ORCHAGENT_EVENT:')) {
+                    try {
+                        const evt = JSON.parse(line.slice('@@ORCHAGENT_EVENT:'.length));
+                        if (evt.usage)
+                            lastUsage = evt.usage;
+                    }
+                    catch { /* ignore parse errors */ }
+                    continue;
+                }
+                if (line.trim() === '.' || line.trim() === '')
+                    continue;
+                process.stderr.write(line + '\n');
+            }
+        });
+        const exitCode = await new Promise((resolve) => {
+            proc.on('close', (code) => resolve(code ?? 1));
+            proc.on('error', (err) => {
+                process.stderr.write(`Error running agent: ${err.message}\n`);
+                resolve(1);
+            });
+        });
+        // Display token usage if available
+        const usage = lastUsage;
+        if (usage && (usage.input_tokens || usage.output_tokens)) {
+            const total = (usage.input_tokens || 0) + (usage.output_tokens || 0);
+            process.stderr.write(chalk_1.default.gray(`${total.toLocaleString()} tokens (${(usage.input_tokens || 0).toLocaleString()} in, ${(usage.output_tokens || 0).toLocaleString()} out)\n`));
+        }
+        // 7. Parse and print result
+        if (stdout.trim()) {
+            try {
+                const result = JSON.parse(stdout.trim());
+                if (exitCode !== 0 && typeof result === 'object' && result !== null && 'error' in result) {
+                    throw new errors_1.CliError(`Agent error: ${result.error}`);
+                }
+                if (exitCode !== 0) {
+                    (0, output_1.printJson)(result);
+                    throw new errors_1.CliError(`Agent exited with code ${exitCode}`);
+                }
+                (0, output_1.printJson)(result);
+            }
+            catch (err) {
+                if (err instanceof errors_1.CliError)
+                    throw err;
+                process.stdout.write(stdout);
+                if (exitCode !== 0) {
+                    throw new errors_1.CliError(`Agent exited with code ${exitCode}`);
+                }
+            }
+        }
+        else if (exitCode !== 0) {
+            throw new errors_1.CliError(`Agent exited with code ${exitCode} (no output)\n\n` +
+                `Common causes:\n` +
+                `  - Missing LLM API key (check ${apiKeyEnvVar || 'API key env var'})\n` +
+                `  - Python SDK not installed (pip install ${sdkPackage})\n` +
+                `  - Syntax error in prompt.md\n`);
+        }
+    }
+    finally {
+        try {
+            await promises_1.default.rm(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
 function parseSkillRef(value) {
     const [ref, versionPart] = value.split('@');
     const version = versionPart?.trim() || 'v1';
@@ -930,10 +1271,57 @@ async function executeLocalFromDir(dirPath, args, options) {
             `Install with: orchagent skill install <org>/<skill>`);
     }
     if (agentType === 'agent') {
-        throw new errors_1.CliError('Agent type cannot be run locally.\n\n' +
-            'Agent type requires a sandbox environment with tool use capabilities.\n' +
-            'Publish first, then run in the cloud:\n' +
-            '  orch publish && orch run <org>/<agent> --data \'{"task": "..."}\'');
+        // Read prompt.md
+        const promptPath = path_1.default.join(resolved, 'prompt.md');
+        let agentPrompt;
+        try {
+            agentPrompt = await promises_1.default.readFile(promptPath, 'utf-8');
+        }
+        catch {
+            throw new errors_1.CliError(`No prompt.md found in ${resolved}`);
+        }
+        // Read schema.json for output schema
+        let agentOutputSchema;
+        try {
+            const schemaRaw = await promises_1.default.readFile(path_1.default.join(resolved, 'schema.json'), 'utf-8');
+            const schemas = JSON.parse(schemaRaw);
+            agentOutputSchema = schemas.output;
+        }
+        catch {
+            // Schema is optional
+        }
+        // Read custom_tools from manifest
+        const customTools = manifest.custom_tools || undefined;
+        // Check for keyed file/mount injection
+        const agentFileArgs = options.file ?? [];
+        const agentKeyedFiles = agentFileArgs.filter(a => isKeyedFileArg(a) !== null);
+        const agentHasInjection = agentKeyedFiles.length > 0 || (options.mount ?? []).length > 0;
+        if (!options.input && !agentHasInjection) {
+            process.stderr.write(`Loaded local agent: ${manifest.name || path_1.default.basename(resolved)}\n\n`);
+            process.stderr.write(`Run with input:\n`);
+            process.stderr.write(`  orch run ${dirPath} --local --data '{\"task\": \"...\"}'\n`);
+            return;
+        }
+        let agentInputData;
+        if (agentHasInjection) {
+            const injected = await buildInjectedPayload({
+                dataOption: options.input,
+                fileArgs: agentKeyedFiles,
+                mountArgs: options.mount,
+            });
+            agentInputData = JSON.parse(injected.body);
+        }
+        else {
+            try {
+                agentInputData = JSON.parse(options.input);
+            }
+            catch {
+                throw new errors_1.CliError('Invalid JSON input');
+            }
+        }
+        const config = await (0, config_1.getResolvedConfig)();
+        await executeAgentLocally(resolved, agentPrompt, agentInputData, agentOutputSchema, customTools, manifest, config, options.provider, options.model);
+        return;
     }
     if (agentType === 'prompt') {
         // Read prompt.md
@@ -969,18 +1357,32 @@ async function executeLocalFromDir(dirPath, args, options) {
             supported_providers: manifest.supported_providers || ['any'],
             default_models: manifest.default_models,
         };
-        if (!options.input) {
+        // Check for keyed file/mount injection
+        const localFileArgs = options.file ?? [];
+        const localKeyedFiles = localFileArgs.filter(a => isKeyedFileArg(a) !== null);
+        const localHasInjection = localKeyedFiles.length > 0 || (options.mount ?? []).length > 0;
+        if (!options.input && !localHasInjection) {
             process.stderr.write(`Loaded local agent: ${agentData.name}\n\n`);
             process.stderr.write(`Run with input:\n`);
             process.stderr.write(`  orch run ${dirPath} --local --data '{...}'\n`);
             return;
         }
         let inputData;
-        try {
-            inputData = JSON.parse(options.input);
+        if (localHasInjection) {
+            const injected = await buildInjectedPayload({
+                dataOption: options.input,
+                fileArgs: localKeyedFiles,
+                mountArgs: options.mount,
+            });
+            inputData = JSON.parse(injected.body);
         }
-        catch {
-            throw new errors_1.CliError('Invalid JSON input');
+        else {
+            try {
+                inputData = JSON.parse(options.input);
+            }
+            catch {
+                throw new errors_1.CliError('Invalid JSON input');
+            }
         }
         const config = await (0, config_1.getResolvedConfig)();
         const result = await executePromptLocally(agentData, inputData, [], config, options.provider, options.model);
@@ -1034,8 +1436,20 @@ async function executeLocalFromDir(dirPath, args, options) {
     catch {
         // No requirements.txt
     }
+    // Check for keyed file/mount injection (tool path)
+    const toolFileArgs = options.file ?? [];
+    const toolKeyedFiles = toolFileArgs.filter(a => isKeyedFileArg(a) !== null);
+    const toolHasInjection = toolKeyedFiles.length > 0 || (options.mount ?? []).length > 0;
     let inputJson = '{}';
-    if (options.input) {
+    if (toolHasInjection) {
+        const injected = await buildInjectedPayload({
+            dataOption: options.input,
+            fileArgs: toolKeyedFiles,
+            mountArgs: options.mount,
+        });
+        inputJson = injected.body;
+    }
+    else if (options.input) {
         try {
             JSON.parse(options.input);
             inputJson = options.input;
@@ -1103,6 +1517,35 @@ async function executeLocalFromDir(dirPath, args, options) {
     }
 }
 // ─── Cloud execution path ───────────────────────────────────────────────────
+function renderProgress(event) {
+    switch (event.type) {
+        case 'turn_start':
+            process.stderr.write(chalk_1.default.gray(`  Turn ${event.turn}/${event.max_turns}\n`));
+            break;
+        case 'tool_call': {
+            const icon = event.tool === 'bash'
+                ? '$'
+                : event.tool === 'read_file'
+                    ? '>'
+                    : event.tool === 'write_file'
+                        ? '<'
+                        : '~';
+            process.stderr.write(chalk_1.default.cyan(`    ${icon} ${event.tool}`) +
+                chalk_1.default.gray(` ${event.args_brief || ''}\n`));
+            break;
+        }
+        case 'tool_result':
+            if (event.status === 'error')
+                process.stderr.write(chalk_1.default.yellow(`      (error)\n`));
+            break;
+        case 'done':
+            process.stderr.write(chalk_1.default.green(`  Done\n`));
+            break;
+        case 'error':
+            process.stderr.write(chalk_1.default.red(`  Error: ${event.message}\n`));
+            break;
+    }
+}
 async function executeCloud(agentRef, file, options) {
     // Merge --input alias into --data
     const dataValue = options.data || options.input;
@@ -1173,6 +1616,7 @@ async function executeCloud(agentRef, file, options) {
     const endpoint = options.endpoint?.trim() || agentMeta.default_endpoint || 'analyze';
     const headers = {
         Authorization: `Bearer ${resolved.apiKey}`,
+        'X-CLI-Version': package_json_1.default.version,
     };
     if (options.tenant) {
         headers['X-OrchAgent-Tenant'] = options.tenant;
@@ -1253,31 +1697,127 @@ async function executeCloud(agentRef, file, options) {
     }
     let body;
     let sourceLabel;
-    const filePaths = [
+    const allFileArgs = [
         ...(options.file ?? []),
         ...(file ? [file] : []),
     ];
-    if (options.data && options.metadata) {
-        throw new errors_1.CliError('Cannot use --data with --metadata. Use one or the other.');
-    }
-    if (options.data && filePaths.length > 0) {
-        // Merge file content into --data
-        const resolvedBody = await resolveJsonBody(options.data);
-        const bodyObj = JSON.parse(resolvedBody);
-        if (agentMeta.type === 'prompt') {
+    // Partition --file args into keyed (key=path) vs unkeyed (plain path)
+    const keyedFileArgs = allFileArgs.filter(a => isKeyedFileArg(a) !== null);
+    const unkeyedFileArgs = allFileArgs.filter(a => isKeyedFileArg(a) === null);
+    const hasKeyed = keyedFileArgs.length > 0;
+    const hasMounts = (options.mount ?? []).length > 0;
+    const hasInjection = hasKeyed || hasMounts;
+    // Cannot mix keyed and unkeyed --file args
+    if (hasInjection && unkeyedFileArgs.length > 0) {
+        throw new errors_1.CliError('Cannot mix keyed --file (key=path) with unkeyed --file (path) in the same command.\n\n' +
+            'Use either:\n' +
+            '  Keyed:   --file code=./main.py --file config=./config.toml\n' +
+            '  Unkeyed: --file ./main.py --file ./config.toml');
+    }
+    if (hasInjection) {
+        // Route to JSON injection path
+        const injected = await buildInjectedPayload({
+            dataOption: options.data,
+            fileArgs: keyedFileArgs,
+            mountArgs: options.mount,
+            llmCredentials,
+        });
+        body = injected.body;
+        sourceLabel = injected.sourceLabel;
+        headers['Content-Type'] = 'application/json';
+    }
+    else {
+        // Existing body construction logic (unkeyed files only)
+        const filePaths = unkeyedFileArgs;
+        if (options.data && options.metadata) {
+            throw new errors_1.CliError('Cannot use --data with --metadata. Use one or the other.');
+        }
+        if (options.data && filePaths.length > 0) {
+            // Merge file content into --data
+            const resolvedBody = await resolveJsonBody(options.data);
+            const bodyObj = JSON.parse(resolvedBody);
+            if (agentMeta.type === 'prompt') {
+                const fieldName = options.fileField || inferFileField(agentMeta.input_schema);
+                if (filePaths.length === 1) {
+                    await validateFilePath(filePaths[0]);
+                    bodyObj[fieldName] = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                    sourceLabel = filePaths[0];
+                }
+                else {
+                    const allContents = {};
+                    for (const fp of filePaths) {
+                        await validateFilePath(fp);
+                        allContents[path_1.default.basename(fp)] = await promises_1.default.readFile(fp, 'utf-8');
+                    }
+                    bodyObj[fieldName] = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                    bodyObj.files = allContents;
+                    sourceLabel = `${filePaths.length} files`;
+                }
+                // Auto-populate filename if schema has it and user didn't provide it
+                if (filePaths.length >= 1 && bodyObj.filename === undefined) {
+                    const schema = agentMeta.input_schema;
+                    const schemaProps = schema?.properties;
+                    if (schemaProps?.filename) {
+                        bodyObj.filename = path_1.default.basename(filePaths[0]);
+                    }
+                }
+                applySchemaDefaults(bodyObj, agentMeta.input_schema);
+                if (llmCredentials)
+                    bodyObj.llm_credentials = llmCredentials;
+                body = JSON.stringify(bodyObj);
+                headers['Content-Type'] = 'application/json';
+            }
+            else {
+                // Tool agents: send files as multipart, --data as metadata
+                let metadata = resolvedBody;
+                if (llmCredentials) {
+                    const metaObj = JSON.parse(metadata);
+                    metaObj.llm_credentials = llmCredentials;
+                    metadata = JSON.stringify(metaObj);
+                }
+                const multipart = await buildMultipartBody(filePaths, metadata);
+                body = multipart.body;
+                sourceLabel = multipart.sourceLabel;
+            }
+        }
+        else if (options.data) {
+            const resolvedBody = await resolveJsonBody(options.data);
+            warnIfLocalPathReference(resolvedBody);
+            if (llmCredentials) {
+                const bodyObj = JSON.parse(resolvedBody);
+                bodyObj.llm_credentials = llmCredentials;
+                body = JSON.stringify(bodyObj);
+            }
+            else {
+                body = resolvedBody;
+            }
+            headers['Content-Type'] = 'application/json';
+        }
+        else if ((filePaths.length > 0 || options.metadata) && agentMeta.type === 'prompt') {
             const fieldName = options.fileField || inferFileField(agentMeta.input_schema);
+            let bodyObj = {};
+            if (options.metadata) {
+                try {
+                    bodyObj = JSON.parse(options.metadata);
+                }
+                catch {
+                    throw new errors_1.CliError('--metadata must be valid JSON.');
+                }
+            }
             if (filePaths.length === 1) {
                 await validateFilePath(filePaths[0]);
-                bodyObj[fieldName] = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                const fileContent = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                bodyObj[fieldName] = fileContent;
                 sourceLabel = filePaths[0];
             }
-            else {
+            else if (filePaths.length > 1) {
                 const allContents = {};
                 for (const fp of filePaths) {
                     await validateFilePath(fp);
                     allContents[path_1.default.basename(fp)] = await promises_1.default.readFile(fp, 'utf-8');
                 }
-                bodyObj[fieldName] = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                const firstContent = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                bodyObj[fieldName] = firstContent;
                 bodyObj.files = allContents;
                 sourceLabel = `${filePaths.length} files`;
             }
@@ -1290,16 +1830,16 @@ async function executeCloud(agentRef, file, options) {
                 }
             }
             applySchemaDefaults(bodyObj, agentMeta.input_schema);
-            if (llmCredentials)
+            if (llmCredentials) {
                 bodyObj.llm_credentials = llmCredentials;
+            }
             body = JSON.stringify(bodyObj);
             headers['Content-Type'] = 'application/json';
         }
-        else {
-            // Tool agents: send files as multipart, --data as metadata
-            let metadata = resolvedBody;
+        else if (filePaths.length > 0 || options.metadata) {
+            let metadata = options.metadata;
             if (llmCredentials) {
-                const metaObj = JSON.parse(metadata);
+                const metaObj = metadata ? JSON.parse(metadata) : {};
                 metaObj.llm_credentials = llmCredentials;
                 metadata = JSON.stringify(metaObj);
             }
@@ -1307,92 +1847,34 @@ async function executeCloud(agentRef, file, options) {
             body = multipart.body;
             sourceLabel = multipart.sourceLabel;
         }
-    }
-    else if (options.data) {
-        const resolvedBody = await resolveJsonBody(options.data);
-        warnIfLocalPathReference(resolvedBody);
-        if (llmCredentials) {
-            const bodyObj = JSON.parse(resolvedBody);
-            bodyObj.llm_credentials = llmCredentials;
-            body = JSON.stringify(bodyObj);
+        else if (llmCredentials) {
+            body = JSON.stringify({ llm_credentials: llmCredentials });
+            headers['Content-Type'] = 'application/json';
         }
         else {
-            body = resolvedBody;
-        }
-        headers['Content-Type'] = 'application/json';
-    }
-    else if ((filePaths.length > 0 || options.metadata) && agentMeta.type === 'prompt') {
-        const fieldName = options.fileField || inferFileField(agentMeta.input_schema);
-        let bodyObj = {};
-        if (options.metadata) {
-            try {
-                bodyObj = JSON.parse(options.metadata);
-            }
-            catch {
-                throw new errors_1.CliError('--metadata must be valid JSON.');
-            }
-        }
-        if (filePaths.length === 1) {
-            await validateFilePath(filePaths[0]);
-            const fileContent = await promises_1.default.readFile(filePaths[0], 'utf-8');
-            bodyObj[fieldName] = fileContent;
-            sourceLabel = filePaths[0];
-        }
-        else if (filePaths.length > 1) {
-            const allContents = {};
-            for (const fp of filePaths) {
-                await validateFilePath(fp);
-                allContents[path_1.default.basename(fp)] = await promises_1.default.readFile(fp, 'utf-8');
-            }
-            const firstContent = await promises_1.default.readFile(filePaths[0], 'utf-8');
-            bodyObj[fieldName] = firstContent;
-            bodyObj.files = allContents;
-            sourceLabel = `${filePaths.length} files`;
-        }
-        // Auto-populate filename if schema has it and user didn't provide it
-        if (filePaths.length >= 1 && bodyObj.filename === undefined) {
-            const schema = agentMeta.input_schema;
-            const schemaProps = schema?.properties;
-            if (schemaProps?.filename) {
-                bodyObj.filename = path_1.default.basename(filePaths[0]);
-            }
-        }
-        applySchemaDefaults(bodyObj, agentMeta.input_schema);
-        if (llmCredentials) {
-            bodyObj.llm_credentials = llmCredentials;
-        }
-        body = JSON.stringify(bodyObj);
-        headers['Content-Type'] = 'application/json';
-    }
-    else if (filePaths.length > 0 || options.metadata) {
-        let metadata = options.metadata;
-        if (llmCredentials) {
-            const metaObj = metadata ? JSON.parse(metadata) : {};
-            metaObj.llm_credentials = llmCredentials;
-            metadata = JSON.stringify(metaObj);
+            const multipart = await buildMultipartBody(undefined, options.metadata);
+            body = multipart.body;
+            sourceLabel = multipart.sourceLabel;
         }
-        const multipart = await buildMultipartBody(filePaths, metadata);
-        body = multipart.body;
-        sourceLabel = multipart.sourceLabel;
-    }
-    else if (llmCredentials) {
-        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;
-    }
+    } // end of non-injection path
     const url = `${resolved.apiUrl.replace(/\/$/, '')}/${org}/${parsed.agent}/${parsed.version}/${endpoint}`;
+    // Enable SSE streaming for agent-type agents (unless --json or --no-stream or --output)
+    const isAgentType = agentMeta.type === 'agent';
+    const wantStream = isAgentType && !options.json && !options.noStream && !options.output;
+    if (wantStream) {
+        headers['Accept'] = 'text/event-stream';
+    }
     const spinner = options.json ? null : (0, spinner_1.createSpinner)(`Running ${org}/${parsed.agent}@${parsed.version}...`);
     spinner?.start();
+    // Agent-type runs can take much longer; use 10 min timeout for streaming
+    const timeoutMs = isAgentType ? 600000 : undefined;
     let response;
     try {
         response = await (0, api_1.safeFetchWithRetryForCalls)(url, {
             method: 'POST',
             headers,
             body,
+            ...(timeoutMs ? { timeoutMs } : {}),
         });
     }
     catch (err) {
@@ -1423,6 +1905,15 @@ async function executeCloud(agentRef, file, options) {
                     '  orch billing balance  # check current balance\n';
             throw new errors_1.CliError(errorMessage, errors_1.ExitCodes.PERMISSION_DENIED);
         }
+        if (errorCode === 'CLI_VERSION_TOO_OLD') {
+            spinner?.fail('CLI version too old');
+            const minVersion = typeof payload === 'object' && payload
+                ? payload.error?.min_version
+                : undefined;
+            throw new errors_1.CliError(`Your CLI version (${package_json_1.default.version}) is too old.\n\n` +
+                (minVersion ? `Minimum required: ${minVersion}\n` : '') +
+                'Update with: npm update -g @orchagent/cli');
+        }
         if (errorCode === 'LLM_KEY_REQUIRED') {
             spinner?.fail('LLM key required');
             throw new errors_1.CliError('This public agent requires you to provide an LLM key.\n' +
@@ -1452,19 +1943,94 @@ async function executeCloud(agentRef, file, options) {
         spinner?.fail(`Run failed: ${message}`);
         throw new errors_1.CliError(message);
     }
+    // Handle SSE streaming response
+    const contentType = response.headers?.get?.('content-type') || '';
+    if (contentType.includes('text/event-stream') && response.body) {
+        spinner?.stop();
+        const { parseSSE } = await Promise.resolve().then(() => __importStar(require('../lib/sse.js')));
+        let finalPayload = null;
+        let hadError = false;
+        process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${parsed.agent}@${parsed.version}:\n`));
+        for await (const { event, data } of parseSSE(response.body)) {
+            if (event === 'progress') {
+                try {
+                    renderProgress(JSON.parse(data));
+                }
+                catch {
+                    // ignore malformed progress events
+                }
+            }
+            else if (event === 'result') {
+                try {
+                    finalPayload = JSON.parse(data);
+                }
+                catch {
+                    finalPayload = data;
+                }
+            }
+            else if (event === 'error') {
+                hadError = true;
+                try {
+                    finalPayload = JSON.parse(data);
+                }
+                catch {
+                    finalPayload = data;
+                }
+            }
+        }
+        process.stderr.write('\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,
+        });
+        if (hadError) {
+            const errMsg = typeof finalPayload === 'object' && finalPayload
+                ? finalPayload.error?.message || 'Agent execution failed'
+                : 'Agent execution failed';
+            throw new errors_1.CliError(errMsg);
+        }
+        if (finalPayload !== null) {
+            (0, output_1.printJson)(finalPayload);
+            if (typeof finalPayload === 'object' && finalPayload !== null && 'metadata' in finalPayload) {
+                const meta = finalPayload.metadata;
+                if (meta) {
+                    const parts = [];
+                    if (typeof meta.processing_time_ms === 'number') {
+                        parts.push(`${(meta.processing_time_ms / 1000).toFixed(1)}s total`);
+                    }
+                    if (typeof meta.execution_time_ms === 'number') {
+                        parts.push(`${(meta.execution_time_ms / 1000).toFixed(1)}s execution`);
+                    }
+                    const usage = meta.usage;
+                    if (usage && (usage.input_tokens || usage.output_tokens)) {
+                        const total = (usage.input_tokens || 0) + (usage.output_tokens || 0);
+                        parts.push(`${total.toLocaleString()} tokens (${(usage.input_tokens || 0).toLocaleString()} in, ${(usage.output_tokens || 0).toLocaleString()} out)`);
+                    }
+                    if (parts.length > 0) {
+                        process.stderr.write(chalk_1.default.gray(`${parts.join(' · ')}\n`));
+                    }
+                }
+            }
+        }
+        return;
+    }
     spinner?.succeed(`Ran ${org}/${parsed.agent}@${parsed.version}`);
     if (!options.json && (0, pricing_1.isPaidAgent)(agentMeta) && pricingInfo?.price_cents && pricingInfo.price_cents > 0) {
         process.stderr.write(`\nCost: $${(pricingInfo.price_cents / 100).toFixed(2)} USD\n`);
     }
-    const inputType = filePaths.length > 0
-        ? 'file'
-        : options.data
-            ? 'json'
-            : sourceLabel === 'stdin'
-                ? 'stdin'
-                : sourceLabel === 'metadata'
-                    ? 'metadata'
-                    : 'empty';
+    const inputType = hasInjection
+        ? 'file_injection'
+        : unkeyedFileArgs.length > 0
+            ? 'file'
+            : options.data
+                ? 'json'
+                : sourceLabel === 'stdin'
+                    ? 'stdin'
+                    : sourceLabel === 'metadata'
+                        ? 'metadata'
+                        : 'empty';
     await (0, analytics_1.track)('cli_run', {
         agent: `${org}/${parsed.agent}@${parsed.version}`,
         input_type: inputType,
@@ -1497,6 +2063,27 @@ async function executeCloud(agentRef, file, options) {
         return;
     }
     (0, output_1.printJson)(payload);
+    // Display timing metadata on stderr (non-json mode only)
+    if (typeof payload === 'object' && payload !== null && 'metadata' in payload) {
+        const meta = payload.metadata;
+        if (meta) {
+            const parts = [];
+            if (typeof meta.processing_time_ms === 'number') {
+                parts.push(`${(meta.processing_time_ms / 1000).toFixed(1)}s total`);
+            }
+            if (typeof meta.execution_time_ms === 'number') {
+                parts.push(`${(meta.execution_time_ms / 1000).toFixed(1)}s execution`);
+            }
+            const usage = meta.usage;
+            if (usage && (usage.input_tokens || usage.output_tokens)) {
+                const total = (usage.input_tokens || 0) + (usage.output_tokens || 0);
+                parts.push(`${total.toLocaleString()} tokens (${(usage.input_tokens || 0).toLocaleString()} in, ${(usage.output_tokens || 0).toLocaleString()} out)`);
+            }
+            if (parts.length > 0) {
+                process.stderr.write(chalk_1.default.gray(`\n${parts.join(' · ')}\n`));
+            }
+        }
+    }
 }
 // ─── Local execution path ───────────────────────────────────────────────────
 async function executeLocal(agentRef, args, options) {
@@ -1555,12 +2142,40 @@ async function executeLocal(agentRef, args, options) {
             `  Install for AI tools:  orchagent skill install ${org}/${parsed.agent}\n` +
             `  Use with an agent:     orchagent run <agent> --skills ${org}/${parsed.agent}`);
     }
-    // Agent type requires a sandbox — cannot run locally
+    // Agent type: execute locally with the agent runner
     if (agentData.type === 'agent') {
-        throw new errors_1.CliError('Agent type cannot be run locally.\n\n' +
-            'Agent type requires a sandbox environment with tool use capabilities.\n\n' +
-            'Remove the --local flag to run in the cloud:\n' +
-            `  orch run ${org}/${parsed.agent}@${parsed.version} --data '{"task": "..."}'`);
+        if (!agentData.prompt) {
+            throw new errors_1.CliError('Agent prompt not available for local execution.\n\n' +
+                'This agent may have local download disabled.\n' +
+                'Remove the --local flag to run in the cloud:\n' +
+                `  orch run ${org}/${parsed.agent}@${parsed.version} --data '{"task": "..."}'`);
+        }
+        if (!options.input) {
+            process.stderr.write(`\nAgent downloaded. Run with:\n`);
+            process.stderr.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --local --data '{\"task\": \"...\"}'\n`);
+            return;
+        }
+        let agentInputData;
+        try {
+            agentInputData = JSON.parse(options.input);
+        }
+        catch {
+            throw new errors_1.CliError('Invalid JSON input');
+        }
+        // Write prompt to temp dir and run
+        const tempAgentDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-agent-${parsed.agent}-${Date.now()}`);
+        await promises_1.default.mkdir(tempAgentDir, { recursive: true });
+        try {
+            await promises_1.default.writeFile(path_1.default.join(tempAgentDir, 'prompt.md'), agentData.prompt);
+            await executeAgentLocally(tempAgentDir, agentData.prompt, agentInputData, agentData.output_schema, undefined, {}, resolved, options.provider, options.model);
+        }
+        finally {
+            try {
+                await promises_1.default.rm(tempAgentDir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        }
+        return;
     }
     // Check for dependencies (orchestrator agents)
     if (agentData.dependencies && agentData.dependencies.length > 0) {
@@ -1610,7 +2225,20 @@ async function executeLocal(agentRef, args, options) {
                 process.stdout.write(`Run with: orch run ${org}/${parsed.agent} --local [args...]\n`);
                 return;
             }
-            await executeBundleAgent(resolved, org, parsed.agent, parsed.version, agentData, args, options.input);
+            // Pre-build injected payload for bundle agent if keyed files/mounts present
+            const bundleFileArgs = options.file ?? [];
+            const bundleKeyedFiles = bundleFileArgs.filter(a => isKeyedFileArg(a) !== null);
+            const bundleHasInjection = bundleKeyedFiles.length > 0 || (options.mount ?? []).length > 0;
+            let bundleInput = options.input;
+            if (bundleHasInjection) {
+                const injected = await buildInjectedPayload({
+                    dataOption: options.input,
+                    fileArgs: bundleKeyedFiles,
+                    mountArgs: options.mount,
+                });
+                bundleInput = injected.body;
+            }
+            await executeBundleAgent(resolved, org, parsed.agent, parsed.version, agentData, args, bundleInput);
             return;
         }
         if (agentData.run_command && (agentData.source_url || agentData.pip_package)) {
@@ -1632,18 +2260,32 @@ async function executeLocal(agentRef, args, options) {
         process.stdout.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --local --input '{...}'\n`);
         return;
     }
+    // Check for keyed file/mount injection
+    const execLocalFileArgs = options.file ?? [];
+    const execLocalKeyedFiles = execLocalFileArgs.filter(a => isKeyedFileArg(a) !== null);
+    const execLocalHasInjection = execLocalKeyedFiles.length > 0 || (options.mount ?? []).length > 0;
     // For prompt-based agents, execute locally
-    if (!options.input) {
+    if (!options.input && !execLocalHasInjection) {
         process.stdout.write(`\nPrompt-based agent ready.\n`);
         process.stdout.write(`Run with: orch run ${org}/${parsed.agent}@${parsed.version} --local --input '{...}'\n`);
         return;
     }
     let inputData;
-    try {
-        inputData = JSON.parse(options.input);
+    if (execLocalHasInjection) {
+        const injected = await buildInjectedPayload({
+            dataOption: options.input,
+            fileArgs: execLocalKeyedFiles,
+            mountArgs: options.mount,
+        });
+        inputData = JSON.parse(injected.body);
     }
-    catch {
-        throw new errors_1.CliError('Invalid JSON input');
+    else {
+        try {
+            inputData = JSON.parse(options.input);
+        }
+        catch {
+            throw new errors_1.CliError('Invalid JSON input');
+        }
     }
     // Handle skill composition
     let skillPrompts = [];
@@ -1680,12 +2322,14 @@ function registerRunCommand(program) {
         .option('--skills <skills>', 'Add skills (comma-separated)')
         .option('--skills-only <skills>', 'Use only these skills')
         .option('--no-skills', 'Ignore default skills')
+        .option('--no-stream', 'Disable real-time streaming for agent-type agents')
         // Cloud-only options
         .option('--endpoint <endpoint>', 'Override agent endpoint (cloud only)')
         .option('--tenant <tenant>', 'Tenant identifier for multi-tenant callers (cloud only)')
         .option('--output <file>', 'Save response body to a file (cloud only)')
-        .option('--file <path...>', 'File(s) to upload (cloud only, can specify multiple)')
+        .option('--file <path...>', 'File(s) to upload or inject as keyed fields (key=path)')
         .option('--file-field <field>', 'Schema field name for file content (cloud only)')
+        .option('--mount <field=dir...>', 'Mount a directory as a JSON field map (field=dir, can specify multiple)')
         .option('--metadata <json>', 'JSON metadata to send with files (cloud only)')
         // Local-only options
         .option('--download-only', 'Just download the agent, do not execute (local only)')
@@ -1701,6 +2345,15 @@ Examples:
     cat input.json | orch run acme/agent --data @-
     orch run acme/image-processor photo.jpg --output result.png
 
+  Keyed file injection (--file key=path):
+    orch run agent --file code=./src/lib.cairo
+    orch run agent --data '{"filter": "test_add"}' --file code=./src/lib.cairo
+    orch run agent --file config=./Scarb.toml --file code=./src/lib.cairo
+
+  Directory mount (--mount field=dir):
+    orch run agent --mount source_files=./src/ --mount test_files=./tests/
+    orch run agent --data '{"filter": "test_add"}' --mount src=./src/ --file config=./Scarb.toml
+
   Local execution (--local):
     orch run orchagent/leak-finder --local --data '{"path": "."}'
     orch run joe/summarizer --local --data '{"text": "Hello world"}'
@@ -1718,6 +2371,10 @@ File handling (cloud):
   input schema. Use --file-field to specify the field name (auto-detected by default).
   For tools, files are uploaded as multipart form data.
 
+  Use --file key=path to inject a file's content at a specific JSON field.
+  Use --mount field=dir to inject a directory tree as a {path: content} map.
+  These produce standard JSON payloads - no server changes needed.
+
 Important: Remote agents cannot access your local filesystem. If your --data payload
 contains keys like 'path', 'directory', 'file', etc., those values will be interpreted
 by the server, not your local machine. To use local files, use --local or --file.