@orchagent/cli 0.3.100 → 0.3.102

package/dist/commands/pull.js

@@ -12,21 +12,10 @@ const child_process_1 = require("child_process");
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
+const resolve_agent_1 = require("../lib/resolve-agent");
 const analytics_1 = require("../lib/analytics");
 const output_1 = require("../lib/output");
 // ─── Helpers ────────────────────────────────────────────────────────────────
-function parsePullRef(value) {
-    const [ref, versionPart] = value.split('@');
-    const version = versionPart?.trim() || 'latest';
-    const segments = ref.split('/');
-    if (segments.length === 1) {
-        return { agent: segments[0], version };
-    }
-    if (segments.length === 2) {
-        return { org: segments[0], agent: segments[1], version };
-    }
-    throw new errors_1.CliError('Invalid agent reference. Use org/agent[@version] or agent[@version] format.');
-}
 function canonicalType(typeValue) {
     const normalized = (typeValue || 'agent').toLowerCase();
     if (['prompt', 'tool', 'agent', 'skill'].includes(normalized))
@@ -123,11 +112,14 @@ async function resolveAgent(config, org, agent, version, workspaceId) {
     if (!config.apiKey) {
         throw new api_1.ApiError(`Agent '${org}/${agent}@${version}' not found`, 404);
     }
-    const userOrg = await (0, api_1.getOrg)(config, workspaceId);
-    if (userOrg.slug !== org) {
-        throw new api_1.ApiError(`Agent '${org}/${agent}@${version}' not found`, 404);
+    // Try workspace-scoped search first, then fall back to personal org.
+    // This handles the case where the user is in a team workspace but the
+    // agent lives in their personal org (or vice versa).  The org_slug
+    // filter inside resolveFromMyAgents prevents cross-org contamination.
+    let data = await resolveFromMyAgents(config, agent, version, org, workspaceId);
+    if (!data && workspaceId) {
+        data = await resolveFromMyAgents(config, agent, version, org, undefined);
     }
-    const data = await resolveFromMyAgents(config, agent, version, org, workspaceId);
     if (!data) {
         throw new api_1.ApiError(`Agent '${org}/${agent}@${version}' not found`, 404);
     }
@@ -135,15 +127,10 @@ async function resolveAgent(config, org, agent, version, workspaceId) {
 }
 async function tryOwnerFallback(config, org, agent, version, workspaceId) {
     try {
-        const myAgents = await (0, api_1.listMyAgents)(config, workspaceId);
-        let match;
-        if (version === 'latest') {
-            match = myAgents
-                .filter(a => a.name === agent && a.org_slug === org)
-                .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())[0];
-        }
-        else {
-            match = myAgents.find(a => a.name === agent && a.version === version && a.org_slug === org);
+        let match = findOwnerMatch(await (0, api_1.listMyAgents)(config, workspaceId), agent, version, org);
+        // Retry without workspace restriction to find agents in personal org
+        if (!match && workspaceId) {
+            match = findOwnerMatch(await (0, api_1.listMyAgents)(config, undefined), agent, version, org);
         }
         if (!match)
             return null;
@@ -154,6 +141,14 @@ async function tryOwnerFallback(config, org, agent, version, workspaceId) {
         return null;
     }
 }
+function findOwnerMatch(agents, agent, version, org) {
+    if (version === 'latest') {
+        return agents
+            .filter(a => a.name === agent && a.org_slug === org)
+            .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())[0];
+    }
+    return agents.find(a => a.name === agent && a.version === version && a.org_slug === org);
+}
 async function resolveFromMyAgents(config, agent, version, org, workspaceId) {
     const agents = await (0, api_1.listMyAgents)(config, workspaceId);
     const matching = agents.filter(a => a.name === agent && a.org_slug === org);
@@ -359,19 +354,12 @@ Examples:
                 process.stdout.write(message);
         };
         const config = await (0, config_1.getResolvedConfig)();
-        const parsed = parsePullRef(agentRef);
-        // Resolve org from workspace / defaultOrg fallback
-        const configFile = await (0, config_1.loadConfig)();
-        const org = parsed.org ?? configFile.workspace ?? config.defaultOrg;
-        if (!org) {
-            throw new errors_1.CliError('Missing org. Use org/agent[@version] format, or set a default org with:\n' +
-                '  orch config set default-org <org>');
-        }
-        // Resolve workspace context for the target org
-        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
-        write(`Resolving ${org}/${parsed.agent}@${parsed.version}...\n`);
+        const { org, agent: agentName, version, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, config, {
+            missingOrgMessage: 'Missing org. Use org/agent[@version] format, or set a default org with:\n  orch config set default-org <org>',
+        });
+        write(`Resolving ${org}/${agentName}@${version}...\n`);
         // Resolve agent data
-        const data = await resolveAgent(config, org, parsed.agent, parsed.version, workspaceId);
+        const data = await resolveAgent(config, org, agentName, version, workspaceId);
         // Reject skills
         if (canonicalType(data.type) === 'skill') {
             throw new errors_1.CliError("This is a skill. Use 'orch skill install <ref>' instead.");
@@ -455,7 +443,7 @@ Examples:
         // Track analytics
         await (0, analytics_1.track)('cli_pull', {
             org,
-            agent: parsed.agent,
+            agent: agentName,
             version: data.version,
             engine,
             source: data.source,
@@ -465,7 +453,7 @@ Examples:
         if (options.json) {
             const result = {
                 success: true,
-                requested_ref: `${org}/${parsed.agent}@${parsed.version}`,
+                requested_ref: `${org}/${agentName}@${version}`,
                 resolved_ref: resolvedRef,
                 output_dir: outputDir,
                 engine,

package/dist/commands/replay.js

@@ -91,6 +91,21 @@ function registerReplayCommand(program) {
         .option('--override-policy <id>', 'Override provider policy ID for this replay')
         .option('--no-wait', 'Queue the replay and return immediately without waiting for results')
         .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+How snapshots work:
+  Every cloud run automatically captures a snapshot of its input, config,
+  secrets, and agent version before execution. This snapshot enables
+  deterministic replay — even if the agent has been updated since.
+
+  Local runs (--local) do not create snapshots and cannot be replayed.
+  Runs created before snapshot support was added also cannot be replayed.
+
+Examples:
+  orch replay a1b2c3d4                  Replay and wait for results
+  orch replay a1b2c3d4 --no-wait        Queue and return immediately
+  orch replay a1b2c3d4 --reason "debug" Replay with audit reason
+  orch replay a1b2c3d4 --json           Output as JSON
+`)
         .action(async (runId, options) => {
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
@@ -109,15 +124,33 @@ function registerReplayCommand(program) {
             throw new errors_1.CliError(`Invalid run ID '${runId}'. Provide a full UUID or a short hex prefix (7+ characters).`);
         }
         // Submit replay request
-        const body = {};
+        const reqBody = {};
         if (options.reason)
-            body.reason = options.reason;
+            reqBody.reason = options.reason;
         if (options.overridePolicy)
-            body.override_provider_policy_id = options.overridePolicy;
-        const replay = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/runs/${resolvedRunId}/replay`, {
-            body: JSON.stringify(body),
-            headers: { 'Content-Type': 'application/json' },
-        });
+            reqBody.override_provider_policy_id = options.overridePolicy;
+        let replay;
+        try {
+            replay = await (0, api_1.request)(config, 'POST', `/workspaces/${workspaceId}/runs/${resolvedRunId}/replay`, {
+                body: JSON.stringify(reqBody),
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        catch (err) {
+            if (err instanceof api_1.ApiError && err.status === 404) {
+                const isSnapshotMissing = err.message.toLowerCase().includes('snapshot');
+                if (isSnapshotMissing) {
+                    throw new errors_1.CliError(`No snapshot available for run ${resolvedRunId.slice(0, 8)}.\n\n` +
+                        `Snapshots are captured automatically for cloud runs. This run may have been:\n` +
+                        `  - A local run (--local), which does not create snapshots\n` +
+                        `  - Created before snapshot support was added\n\n` +
+                        `Run \`orch logs ${resolvedRunId.slice(0, 8)}\` to inspect the original run.`);
+                }
+                throw new errors_1.CliError(`Run ${resolvedRunId.slice(0, 8)} not found. ` +
+                    `Check the run ID and workspace, or run \`orch logs\` to list recent runs.`);
+            }
+            throw err;
+        }
         if (options.json && options.wait === false) {
             (0, output_1.printJson)(replay);
             return;

package/dist/commands/run.js

@@ -54,6 +54,7 @@ const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const dotenv_1 = require("../lib/dotenv");
 const config_1 = require("../lib/config");
+const resolve_agent_1 = require("../lib/resolve-agent");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
 const output_1 = require("../lib/output");
@@ -84,18 +85,6 @@ function localCommandForEntrypoint(entrypoint) {
     }
     return 'python3';
 }
-function parseAgentRef(value) {
-    const [ref, versionPart] = value.split('@');
-    const version = versionPart?.trim() || DEFAULT_VERSION;
-    const segments = ref.split('/');
-    if (segments.length === 1) {
-        return { agent: segments[0], version };
-    }
-    if (segments.length === 2) {
-        return { org: segments[0], agent: segments[1], version };
-    }
-    throw new errors_1.CliError('Invalid agent reference. Use org/agent or agent format.');
-}
 function canonicalAgentType(typeValue) {
     const normalized = (typeValue || 'agent').toLowerCase();
     // Handle legacy type names: agentic → agent, code → tool
@@ -798,6 +787,13 @@ async function detectAllLlmKeys(supportedProviders, config) {
     return providers;
 }
 async function executePromptLocally(agentData, inputData, skillPrompts = [], config, providerOverride, modelOverride) {
+    // Auto-detect provider from model name if not explicitly specified
+    if (!providerOverride && modelOverride) {
+        const detected = (0, llm_1.detectProviderFromModel)(modelOverride);
+        if (detected) {
+            providerOverride = detected;
+        }
+    }
     if (providerOverride) {
         (0, llm_1.validateProvider)(providerOverride);
     }
@@ -816,7 +812,7 @@ async function executePromptLocally(agentData, inputData, skillPrompts = [], con
             throw new errors_1.CliError(`No LLM key found for: ${providers}\n` +
                 `Set an environment variable (e.g., OPENAI_API_KEY), run 'orch secrets set <PROVIDER>_API_KEY <key>', or configure in web dashboard`);
         }
-        if (modelOverride && !providerOverride && allProviders.length > 1) {
+        if (modelOverride && allProviders.length > 1) {
             process.stderr.write(`Warning: --model specified without --provider. The model '${modelOverride}' will be used for all ${allProviders.length} fallback providers, which may cause errors if the model is incompatible.\n` +
                 `Consider specifying --provider to ensure correct model/provider pairing.\n\n`);
         }
@@ -866,6 +862,13 @@ async function executeAgentLocally(agentDir, prompt, inputData, outputSchema, cu
         throw new errors_1.CliError('Python 3 is required for local agent execution.\n' +
             'Install Python 3: https://python.org/downloads');
     }
+    // Auto-detect provider from model name if not explicitly specified
+    if (!providerOverride && modelOverride) {
+        const detected = (0, llm_1.detectProviderFromModel)(modelOverride);
+        if (detected) {
+            providerOverride = detected;
+        }
+    }
     // 2. Detect LLM provider + key
     const supportedProviders = manifest?.supported_providers || ['any'];
     const providersToCheck = providerOverride
@@ -1869,15 +1872,8 @@ async function executeCloud(agentRef, file, options) {
     if (!resolved.apiKey) {
         throw new errors_1.CliError('Missing API key. Run `orchagent login` first.');
     }
-    const parsed = parseAgentRef(agentRef);
-    const configFile = await (0, config_1.loadConfig)();
-    const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-    if (!org) {
-        throw new errors_1.CliError('Missing org. Use org/agent or set default org.');
-    }
-    // Resolve workspace context for the target org
-    const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
-    const agentMeta = await (0, api_1.getAgentWithFallback)(resolved, org, parsed.agent, parsed.version, workspaceId);
+    const { org, agent: agentName, version, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, resolved);
+    const agentMeta = await (0, api_1.getAgentWithFallback)(resolved, org, agentName, version, workspaceId);
     const cloudType = canonicalAgentType(agentMeta.type);
     const cloudEngine = resolveExecutionEngine({
         type: agentMeta.type,
@@ -1891,10 +1887,8 @@ async function executeCloud(agentRef, file, options) {
         const agentRequiredSecrets = agentMeta.required_secrets;
         if (agentRequiredSecrets?.length) {
             try {
-                // Use already-resolved workspaceId (or fall back to config workspace slug)
-                const wsId = workspaceId ?? (configFile.workspace ? (await (0, api_1.resolveWorkspaceIdForOrg)(resolved, configFile.workspace)) : undefined);
-                if (wsId) {
-                    const secretsResult = await (0, api_1.request)(resolved, 'GET', `/workspaces/${wsId}/secrets`);
+                if (workspaceId) {
+                    const secretsResult = await (0, api_1.request)(resolved, 'GET', `/workspaces/${workspaceId}/secrets`);
                     const existingNames = new Set(secretsResult.secrets.map((s) => s.name));
                     const missing = agentRequiredSecrets.filter((s) => !existingNames.has(s));
                     if (missing.length > 0) {
@@ -1918,7 +1912,7 @@ async function executeCloud(agentRef, file, options) {
     // --estimate-only: show cost estimate and exit without running
     if (options.estimate || options.estimateOnly) {
         try {
-            const est = await (0, api_1.getAgentCostEstimate)(resolved, org, parsed.agent, parsed.version);
+            const est = await (0, api_1.getAgentCostEstimate)(resolved, org, agentName, version);
             const e = est.estimate;
             if (e.sample_size === 0) {
                 process.stderr.write(chalk_1.default.yellow('\nNo run history available for cost estimation.\n'));
@@ -1988,18 +1982,8 @@ async function executeCloud(agentRef, file, options) {
             throw new errors_1.CliError('When using --key, you must also specify --provider (openai, anthropic, or gemini)');
         }
         (0, llm_1.validateProvider)(effectiveProvider);
-        if (options.model && effectiveProvider) {
-            const modelLower = options.model.toLowerCase();
-            const providerPatterns = {
-                openai: /^(gpt-|o1-|o3-|davinci|text-)/,
-                anthropic: /^claude-/,
-                gemini: /^gemini-/,
-                ollama: /^(llama|mistral|deepseek|phi|qwen)/,
-            };
-            const expectedPattern = providerPatterns[effectiveProvider];
-            if (expectedPattern && !expectedPattern.test(modelLower)) {
-                process.stderr.write(`Warning: Model '${options.model}' may not be a ${effectiveProvider} model.\n\n`);
-            }
+        if (options.model) {
+            (0, llm_1.warnProviderModelMismatch)(options.model, effectiveProvider);
         }
         llmKey = options.key;
         llmProvider = effectiveProvider;
@@ -2010,17 +1994,7 @@ async function executeCloud(agentRef, file, options) {
             (0, llm_1.validateProvider)(effectiveProvider);
             providersToCheck = [effectiveProvider];
             if (options.model) {
-                const modelLower = options.model.toLowerCase();
-                const providerPatterns = {
-                    openai: /^(gpt-|o1-|o3-|davinci|text-)/,
-                    anthropic: /^claude-/,
-                    gemini: /^gemini-/,
-                    ollama: /^(llama|mistral|deepseek|phi|qwen)/,
-                };
-                const expectedPattern = providerPatterns[effectiveProvider];
-                if (expectedPattern && !expectedPattern.test(modelLower)) {
-                    process.stderr.write(`Warning: Model '${options.model}' may not be a ${effectiveProvider} model.\n\n`);
-                }
+                (0, llm_1.warnProviderModelMismatch)(options.model, effectiveProvider);
             }
         }
         const detected = await (0, llm_1.detectLlmKey)(providersToCheck, resolved);
@@ -2245,7 +2219,7 @@ async function executeCloud(agentRef, file, options) {
         }
     } // end of non-injection path
     const verboseQs = options.verbose ? '?verbose=true' : '';
-    const url = `${resolved.apiUrl.replace(/\/$/, '')}/${org}/${parsed.agent}/${parsed.version}/${endpoint}${verboseQs}`;
+    const url = `${resolved.apiUrl.replace(/\/$/, '')}/${org}/${agentName}/${version}/${endpoint}${verboseQs}`;
     // Enable SSE streaming for sandbox-backed engines (unless --json or --no-stream or --output)
     const isManagedLoopAgent = cloudType === 'agent' && cloudEngine === 'managed_loop';
     const isCodeRuntimeAgent = cloudEngine === 'code_runtime';
@@ -2257,13 +2231,13 @@ async function executeCloud(agentRef, file, options) {
     }
     // Print verbose debug info before request
     if (options.verbose && !options.json) {
-        process.stderr.write(chalk_1.default.gray(`\n[verbose] ${org}/${parsed.agent}@${parsed.version}\n` +
+        process.stderr.write(chalk_1.default.gray(`\n[verbose] ${org}/${agentName}@${version}\n` +
             `[verbose] type=${cloudType}  engine=${cloudEngine}  endpoint=${endpoint}\n` +
             `[verbose] stream=${wantStream ? 'yes' : 'no'}  url=${url}\n`));
     }
     const { spinner, dispose: disposeSpinner } = options.json
         ? { spinner: null, dispose: () => { } }
-        : (0, spinner_1.createElapsedSpinner)(`Running ${org}/${parsed.agent}@${parsed.version}...`);
+        : (0, spinner_1.createElapsedSpinner)(`Running ${org}/${agentName}@${version}...`);
     spinner?.start();
     // Streamed sandbox runs can take longer; use 10 min timeout (or --wait-timeout).
     const waitTimeoutSec = options.waitTimeout ? parseInt(options.waitTimeout, 10) : undefined;
@@ -2432,11 +2406,11 @@ async function executeCloud(agentRef, file, options) {
         let finalPayload = null;
         let hadError = false;
         if (options.verbose) {
-            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${parsed.agent}@${parsed.version} (verbose):\n`));
+            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${agentName}@${version} (verbose):\n`));
             process.stderr.write(chalk_1.default.gray(`  type=${cloudType}  engine=${cloudEngine}  endpoint=${endpoint}\n`));
         }
         else {
-            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${parsed.agent}@${parsed.version}:\n`));
+            process.stderr.write(chalk_1.default.gray(`\nStreaming ${org}/${agentName}@${version}:\n`));
         }
         let progressErrorShown = false;
         let streamTimedOut = false;
@@ -2497,7 +2471,7 @@ async function executeCloud(agentRef, file, options) {
                     ? ''
                     : 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}`,
+                agent: `${org}/${agentName}@${version}`,
                 input_type: hasInjection ? 'file_injection' : unkeyedFileArgs.length > 0 ? 'file' : options.data ? 'json' : 'empty',
                 mode: 'cloud',
                 streamed: true,
@@ -2508,7 +2482,7 @@ async function executeCloud(agentRef, file, options) {
             throw err;
         }
         await (0, analytics_1.track)('cli_run', {
-            agent: `${org}/${parsed.agent}@${parsed.version}`,
+            agent: `${org}/${agentName}@${version}`,
             input_type: hasInjection ? 'file_injection' : unkeyedFileArgs.length > 0 ? 'file' : options.data ? 'json' : 'empty',
             mode: 'cloud',
             streamed: true,
@@ -2549,14 +2523,14 @@ async function executeCloud(agentRef, file, options) {
                     }
                     const runId = response.headers?.get?.('x-run-id');
                     if (runId) {
-                        process.stderr.write(chalk_1.default.gray(`View logs: orch logs ${runId}\n`));
+                        process.stderr.write(chalk_1.default.gray(`Snapshot saved · Logs: orch logs ${runId}  · Replay: orch replay ${runId}\n`));
                     }
                 }
             }
         }
         return;
     }
-    spinner?.succeed(`Ran ${org}/${parsed.agent}@${parsed.version}`);
+    spinner?.succeed(`Ran ${org}/${agentName}@${version}`);
     const inputType = hasInjection
         ? 'file_injection'
         : unkeyedFileArgs.length > 0
@@ -2569,7 +2543,7 @@ async function executeCloud(agentRef, file, options) {
                         ? 'metadata'
                         : 'empty';
     await (0, analytics_1.track)('cli_run', {
-        agent: `${org}/${parsed.agent}@${parsed.version}`,
+        agent: `${org}/${agentName}@${version}`,
         input_type: inputType,
         mode: 'cloud',
     });
@@ -2638,7 +2612,7 @@ async function executeCloud(agentRef, file, options) {
             }
             const runId = response.headers?.get?.('x-run-id');
             if (runId) {
-                process.stderr.write(chalk_1.default.gray(`View logs: orch logs ${runId}\n`));
+                process.stderr.write(chalk_1.default.gray(`Snapshot saved · Logs: orch logs ${runId}  · Replay: orch replay ${runId}\n`));
             }
         }
     }
@@ -2657,34 +2631,24 @@ async function executeLocal(agentRef, args, options) {
         options.input = JSON.stringify({ path: options.path });
     }
     if (options.model && options.provider) {
-        const modelLower = options.model.toLowerCase();
-        const providerPatterns = {
-            openai: /^(gpt-|o1-|o3-|davinci|text-)/,
-            anthropic: /^claude-/,
-            gemini: /^gemini-/,
-            ollama: /^(llama|mistral|deepseek|phi|qwen)/,
-        };
-        const expectedPattern = providerPatterns[options.provider];
-        if (expectedPattern && !expectedPattern.test(modelLower)) {
-            process.stderr.write(`Warning: Model '${options.model}' may not be a ${options.provider} model.\n\n`);
+        (0, llm_1.warnProviderModelMismatch)(options.model, options.provider);
+    }
+    else if (options.model && !options.provider) {
+        const detected = (0, llm_1.detectProviderFromModel)(options.model);
+        if (detected) {
+            options.provider = detected;
+            process.stderr.write(`Auto-detected provider: ${detected} (from model '${options.model}')\n\n`);
         }
     }
     const resolved = await (0, config_1.getResolvedConfig)();
-    const parsed = parseAgentRef(agentRef);
-    const configFile = await (0, config_1.loadConfig)();
-    const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-    if (!org) {
-        throw new errors_1.CliError('Missing org. Use org/agent format.');
-    }
-    // Resolve workspace context for the target org
-    const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
+    const { org, agent: localAgentName, version: localVersion, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(agentRef, resolved);
     // Download agent definition with spinner
-    const agentData = await (0, spinner_1.withSpinner)(`Downloading ${org}/${parsed.agent}@${parsed.version}...`, async () => {
+    const agentData = await (0, spinner_1.withSpinner)(`Downloading ${org}/${localAgentName}@${localVersion}...`, async () => {
         try {
-            return await downloadAgent(resolved, org, parsed.agent, parsed.version, workspaceId);
+            return await downloadAgent(resolved, org, localAgentName, localVersion, workspaceId);
         }
         catch (err) {
-            const agentMeta = await (0, api_1.getPublicAgent)(resolved, org, parsed.agent, parsed.version);
+            const agentMeta = await (0, api_1.getPublicAgent)(resolved, org, localAgentName, localVersion);
             return {
                 type: agentMeta.type || 'agent',
                 run_mode: agentMeta.run_mode ?? null,
@@ -2696,7 +2660,7 @@ async function executeLocal(agentRef, args, options) {
                 supported_providers: agentMeta.supported_providers || ['any'],
             };
         }
-    }, { successText: `Downloaded ${org}/${parsed.agent}@${parsed.version}` });
+    }, { successText: `Downloaded ${org}/${localAgentName}@${localVersion}` });
     const localType = canonicalAgentType(agentData.type);
     const localEngine = resolveExecutionEngine(agentData);
     // Skills cannot be run directly
@@ -2704,8 +2668,8 @@ async function executeLocal(agentRef, args, options) {
         throw new errors_1.CliError('Skills cannot be run directly.\n\n' +
             'Skills are instructions meant to be injected into AI agent contexts.\n\n' +
             'Options:\n' +
-            `  Install for AI tools:  orchagent skill install ${org}/${parsed.agent}\n` +
-            `  Use with an agent:     orchagent run <agent> --skills ${org}/${parsed.agent}`);
+            `  Install for AI tools:  orchagent skill install ${org}/${localAgentName}\n` +
+            `  Use with an agent:     orchagent run <agent> --skills ${org}/${localAgentName}`);
     }
     // Managed-loop agents execute locally with the agent runner.
     if (localEngine === 'managed_loop') {
@@ -2713,11 +2677,11 @@ async function executeLocal(agentRef, args, options) {
             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": "..."}'`);
+                `  orch run ${org}/${localAgentName}@${localVersion} --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`);
+            process.stderr.write(`  orch run ${org}/${localAgentName}@${localVersion} --local --data '{\"task\": \"...\"}'\n`);
             return;
         }
         // Resolve @file.json / @- stdin syntax before parsing
@@ -2731,7 +2695,7 @@ async function executeLocal(agentRef, args, options) {
         }
         warnInputSchemaErrors(agentInputData, agentData.input_schema);
         // Write prompt to temp dir and run
-        const tempAgentDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-agent-${parsed.agent}-${Date.now()}`);
+        const tempAgentDir = path_1.default.join(os_1.default.tmpdir(), `orchagent-agent-${localAgentName}-${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);
@@ -2761,7 +2725,7 @@ async function executeLocal(agentRef, args, options) {
         }
         if (choice === 'server') {
             process.stderr.write(`\nRun without --local for server execution:\n`);
-            process.stderr.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --data '{...}'\n\n`);
+            process.stderr.write(`  orch run ${org}/${localAgentName}@${localVersion} --data '{...}'\n\n`);
             process.exit(0);
         }
         await downloadDependenciesRecursively(resolved, depStatuses, new Set(), workspaceId);
@@ -2784,13 +2748,13 @@ async function executeLocal(agentRef, args, options) {
         }
     }
     // Save locally
-    const agentDir = await saveAgentLocally(org, parsed.agent, agentData);
+    const agentDir = await saveAgentLocally(org, localAgentName, agentData);
     process.stderr.write(`\nAgent saved to: ${agentDir}\n`);
     if (localEngine === 'code_runtime') {
         if (agentData.has_bundle) {
             if (options.downloadOnly) {
                 process.stdout.write(`\nCode runtime bundle is available for local execution.\n`);
-                process.stdout.write(`Run with: orch run ${org}/${parsed.agent} --local [args...]\n`);
+                process.stdout.write(`Run with: orch run ${org}/${localAgentName} --local [args...]\n`);
                 return;
             }
             // Pre-build injected payload for bundle agent if keyed files/mounts present
@@ -2806,13 +2770,13 @@ async function executeLocal(agentRef, args, options) {
                 });
                 bundleInput = injected.body;
             }
-            await executeBundleAgent(resolved, org, parsed.agent, parsed.version, agentData, args, bundleInput, workspaceId);
+            await executeBundleAgent(resolved, org, localAgentName, localVersion, agentData, args, bundleInput, workspaceId);
             return;
         }
         if (agentData.run_command && (agentData.source_url || agentData.pip_package)) {
             if (options.downloadOnly) {
                 process.stdout.write(`\nTool ready for local execution.\n`);
-                process.stdout.write(`Run with: orch run ${org}/${parsed.agent} --local [args...]\n`);
+                process.stdout.write(`Run with: orch run ${org}/${localAgentName} --local [args...]\n`);
                 return;
             }
             await executeTool(agentData, args);
@@ -2820,12 +2784,12 @@ async function executeLocal(agentRef, args, options) {
         }
         // Fallback: code runtime agent doesn't support local execution.
         process.stdout.write(`\nThis code runtime agent is configured for server execution.\n`);
-        process.stdout.write(`\nRun without --local: orch run ${org}/${parsed.agent}@${parsed.version} --data '{...}'\n`);
+        process.stdout.write(`\nRun without --local: orch run ${org}/${localAgentName}@${localVersion} --data '{...}'\n`);
         return;
     }
     if (options.downloadOnly) {
         process.stdout.write(`\nAgent downloaded. Run with:\n`);
-        process.stdout.write(`  orch run ${org}/${parsed.agent}@${parsed.version} --local --input '{...}'\n`);
+        process.stdout.write(`  orch run ${org}/${localAgentName}@${localVersion} --local --input '{...}'\n`);
         return;
     }
     // Check for keyed file/mount injection
@@ -2835,7 +2799,7 @@ async function executeLocal(agentRef, args, options) {
     // Direct LLM agents execute locally via prompt composition.
     if (!options.input && !execLocalHasInjection) {
         process.stdout.write(`\nAgent ready.\n`);
-        process.stdout.write(`Run with: orch run ${org}/${parsed.agent}@${parsed.version} --local --input '{...}'\n`);
+        process.stdout.write(`Run with: orch run ${org}/${localAgentName}@${localVersion} --local --input '{...}'\n`);
         return;
     }
     let inputData;